Ss14 Documentation Writing

Базовые правила

Язык

1. Документацию пиши на английском языке.
2. Идентификаторы и XML-теги не искажай и не смешивай языки в одном doc-блоке.

C# и SWSL

1. Используй /// <summary> как основной формат документации в коде.
2. Документируй публичные методы, публичные API-точки и DataField-контракты через summary.
3. Для partial-классов добавляй короткое описание роли конкретной части сразу под объявлением класса и перед блоком зависимостей.
4. Для сложной математики, нестандартных переходов состояния, предикшн-нюансов и workaround-логики добавляй короткий комментарий над блоком логики, даже если у метода уже есть summary.
5. Не комментируй каждую строку и каждый очевидный if "ради комментарирования".
6. Проверяй валидность XML-доков: корректные теги и регистр (</summary>, не </summarY>).

YAML прототипы

1. Разделяй группы прототипов комментариями.
2. Если комментарий описывает поведение прототипа, ограничивайся одним предложением.
3. Не превращай прототипы в "простыню" из многострочных объяснений.
4. Не используй edit-маркеры как "документацию" (Start/End-блоки без смысла для поведения).

FTL

1. Комментарии в FTL используй только для редкого разделения на группы.
2. Всегда ставь пробел между ## и названием группы: ## Group Name.
3. Не используй сломанные заголовки вида ##bombs.
4. Не спамь заголовками перед каждым несколькими ключами.

Workflow для документирования подсистемы

1. Найди основной контракт подсистемы: что обязаны знать внешние вызовы.
2. Просмотри все основные callsite в server/shared/client.
3. Отметь нестандартные вызовы (дополнительные флаги, special-case пути, обход стандартных проверок).
4. Зафиксируй эти места в summary и коротких точечных комментариях "почему так".
5. Удали шум: любые комментарии, которые просто пересказывают строку кода.

Decision Tree

1. Это публичный контракт/метод/тип? Пиши summary.
2. Это сложный, неочевидный блок (математика, предикшн, workaround)? Пиши короткий комментарий над блоком + оставляй summary на уровне метода.
3. Это очевидный локальный код? Не комментируй.
4. Это partial-часть большой системы? Добавь заголовок роли части и смысл блока зависимостей.
5. Это YAML/FTL группировка? Дай краткий разделитель, без длинного описания.

Паттерны ✅

1. ClickableSystem и CheckClick(...) используют summary для контракта и точечные комментарии в местах со сложными преобразованиями координат.
2. MimePowersSystem.OnInvisibleWall(...) документирован summary, а комментарии оставлены только на критичных проверках.
3. В AccessOverriderSystem публичные методы сочетают summary и remarks, когда нужно зафиксировать инвариант поведения.
4. BaseContainer и SharedContainerSystem.Remove(...) показывают стабильный стиль API-документации: summary + remarks + описанные параметры.
5. В SharedScp096System логика декомпозирована на partial-части с отдельными блоками ответственности и зависимостей.
6. Scp096PhotoSystem и ArtifactScp096MadnessSystem показывают, что документация должна учитывать нестандартные флаги вызова (TryAddTarget(..., true, true)), а не только default-путь.
7. В YAML-каталогах разделители уровня # Rank 2 / # Rank 3 делают большие списки читаемыми без перегруза.
8. В FTL корректный разделитель группы имеет вид ## Strings for the battery ... и не ломает парсинг.

Анти-паттерны ❌

1. Невалидные XML-теги в доках (</summarY> и другие опечатки).
2. Русскоязычные и смешанные по языку doc-комментарии в коде.
3. Комментарии-очевидности, которые просто дублируют строку кода.
4. Использование TODO/HACK/FIXME как "документации поведения" вместо исправления или нормального пояснения.
5. Многострочные объяснения в YAML там, где достаточно одной фразы.
6. Edit-маркеры (Sunrise-Start/End, Fire added start/end) вместо поведенческого описания.
7. FTL-заголовки без пробела после ## (##bombs).
8. Частые или декоративные FTL-разделители (##########), которые не помогают навигации.

Примеры из кода

Пример 1: summary + точечные комментарии на сложной логике

/// <summary>
/// Handles click detection for sprites.
/// </summary>
public sealed class ClickableSystem : EntitySystem
{
    /// <summary>
    /// Used to check whether a click worked.
    /// </summary>
    public bool CheckClick(...)
    {
        // First we get localPos, the clicked location in the sprite-coordinate frame.
        ...
        // Next check each individual sprite layer using automatically computed click maps.
        ...
    }
}

Комментарий: summary держит API-контракт, а inline-комментарии остаются только у неочевидных шагов.

Пример 2: короткие комментарии только на реально важных проверках

/// <summary>
/// Creates an invisible wall in a free space after some checks.
/// </summary>
private void OnInvisibleWall(Entity<MimePowersComponent> ent, ref InvisibleWallActionEvent args)
{
    // Get the tile in front of the mime
    ...
    // Check if the tile is blocked by a wall or mob, and don't create the wall if so
    ...
    // Make sure we set the invisible wall to despawn properly
    ...
}

Комментарий: комментарии не засоряют метод, а поясняют только проверки и последствия.

Пример 3: summary + remarks для инвариантов

/// <summary>
/// Returns true if there is an ID in privileged slot and said ID satisfies access requirements.
/// </summary>
/// <remarks>
/// Other code relies on the fact this returns false if privileged Id is null.
/// </remarks>
private bool PrivilegedIdIsAuthorized(...)
{
    ...
}

Комментарий: remarks фиксирует инвариант, который иначе легко нарушить при рефакторе.

Пример 4: partial-декомпозиция + анализ нестандартных вызовов

public abstract partial class SharedScp096System
{
    /*
     * Target-handling part of the system.
     */
    [Dependency] private readonly SharedPopupSystem _popup = default!;
    ...
}

if (!_scp096.TryAddTarget((uid, scp096), args.Examiner, true, true))
    continue;

Комментарий: для таких систем документируй не только "что делает часть", но и зачем callsite включает нестандартные флаги.

Пример 5: YAML-группировка без перегруза

# Rank 2
- type: cargoProduct
  id: CargoDoubleEmergencyTank

# Rank 3
- type: cargoProduct
  id: CargoFulton

Комментарий: короткий разделитель ускоряет чтение и не превращается в дополнительный "документ внутри прототипа".

Пример 6: FTL-разделители

## Strings for the battery (SMES/substation) menu
battery-menu-out = OUT

##bombs
uplink-pizza-bomb-name = Nefarious Pizza bomb

Комментарий: первый заголовок корректный, второй - сломанный из-за отсутствия пробела после ##.

Чеклист перед PR

1. Все новые doc-комментарии в коде на английском.
2. Для публичных и межсистемных контрактов добавлен summary.
3. В partial-системах есть краткое описание роли части.
4. Сложные блоки получили короткое пояснение "почему".
5. В YAML комментарии короткие и только по делу.
6. В FTL групповые комментарии редкие и только в формате ## Group Name.
7. Нет невалидных XML-тегов и сломанных FTL-заголовков.

Правило расширения

1. Добавляй новые правила только после подтверждения свежим кодом и просмотром callsite.
2. Спорные или legacy-примеры сначала фиксируй как анти-паттерны.
3. Если тема разрастается (например, только guidebook XML или только UI-локализация), выноси в отдельный специализированный skill.

Документируй так, чтобы следующий разработчик понял контракт без археологии кода 🙂