AGENTS.md
56 lines
| 3.4 KiB
| text/x-minidsrc
|
MarkdownLexer
cin
|
r29 | # AGENTS.md | ||
| ## Проектные договоренности | ||||
|
cin
|
r51 | - для управления исходным кодом используется Mercurial | ||
|
cin
|
r29 | ### Публичное API библиотек | ||
| - Предпочтителен `non-null` подход. | ||||
| - Там, где значение живет в Gradle Provider API, возвращается `Provider<T>` (не `null`). | ||||
| - Там, где lookup синхронный, возвращается `Optional<T>` (не `null`). | ||||
| - `find*` рассматривается как синоним legacy `get*` (поиск без `fail-fast`). | ||||
| - `require*` это `find*` + `fail-fast` с понятной ошибкой в месте вызова. | ||||
| - Для нового API предпочтительны формы `find/require`; новые `get*` по возможности не добавлять. | ||||
|
cin
|
r46 | - Интерфейсы и классы, описывающие модели DSL должны иметь суффикс `Spec` у моделей описывающих уровень сервисов и состояние сценария сборки такого суффикса не должно быть. | ||
| - Модель расширения на уровне проекта должна иметь суффикс `Extension`. | ||||
|
cin
|
r39 | |||
|
cin
|
r43 | ### Документация | ||
| - документирование кода должно быть на английском языке | ||||
| - к публичному API | ||||
| - описание должно отражать назначение, где используется и какое влияние оказывает на остальные части программы | ||||
| - давать небольшое описание концепции, а также краткие примеры | ||||
| - к приватному API достаточно давать краткую справку о назначении и использовании | ||||
| - реализацию алгоритмов в коде сопровождать комментариями с пояснениями, тривиальные операции пояснять не требуется. | ||||
| - документация должна формироваться согласно требованиям по форматированию типа javadoc, jsdoc и т.п., в зависимости от используемых в проекте языках и инструментах. | ||||
|
cin
|
r39 | ## Identity-first modeling | ||
| Prefer an **identity-first** split between: | ||||
| - **identity objects** used for discovery and selection | ||||
| - **stateful/materialized objects** obtained through separate API calls | ||||
| ### Rules | ||||
| - Objects intended for replayable observation (`all(...)`, similar collection APIs) should be **identity objects**. | ||||
| - Identity objects must be: | ||||
| - cheap to create | ||||
| - effectively immutable | ||||
| - limited to identity and cheap selection metadata | ||||
| - Heavy, computed, provider-based, or runtime-bound state must be resolved separately. | ||||
| - Aggregate content should be accessed through dedicated lookup/materialization APIs. | ||||
| - Eager observation of identity is acceptable. | ||||
| - Eager observation of computed state is not. | ||||
| ### Do not | ||||
| - Do not store heavy computed state inside identity objects. | ||||
| - Do not store runtime references to foreign domains inside identity objects. | ||||
| - Do not use custom events when replayable identity registries plus on-demand lookup are sufficient. | ||||
| ### Rule of thumb | ||||
| **Identity objects contain selection metadata. | ||||
| Aggregate content is obtained separately, on demand.** | ||||