Обновить доки по закрытию остатков код-стайла
Аудит §2 переписан под решения (var-гейт, LF, дедуп закрыт — дублей нет); backlog: TD-COMMENTS-IFACE п.1–3 закрыты, TD-STYLE-ANALYZERS закрыт; STATUS.md — новый блок захода, устаревший блок «Осталось (в backlog)» в шапке удалён; план и ledger захода.
This commit is contained in:
Rustam Khalimov
@@ -1,50 +1,57 @@
|
||||
# Аудит кода на соответствие код-стайлу «Дейл» (2026-09-11)
|
||||
|
||||
> Отчёт прохода по всему C#-коду (`src/**/*.cs`, 928 файлов, без `bin/obj`).
|
||||
> Правила — `docs/spec/Код-стайл-Дейл.md`. Проверка: сборка 4 решений + все тесты.
|
||||
|
||||
## 1. Исправлено (применено и проверено)
|
||||
|
||||
| Пункт | Правило | Было | Стало | Инструмент |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Блочный `<summary>` | §5 | 5286 однострочных/инлайн (833 файла) | 0 | `scripts/fix_summary_blocks.py --apply` |
|
||||
| XML-док на private/internal | §5 | 2028 блоков (359 файлов) | 0 (понижены до `//`) | `scripts/fix_private_docs.py --apply` |
|
||||
| Квалификация `this.` | §4 | 124 | **0** | разовый Roslyn-инструмент (семантический) |
|
||||
| Приватные instance-поля | §1 | camelCase (`logger`) | `_camelCase` (`_logger`) | разовый Roslyn-инструмент |
|
||||
| Приватные `static readonly`/`const` | §1 | — | Pascal (`DefaultTimeout`) | разовый Roslyn-инструмент |
|
||||
|
||||
Дополнительно в `.editorconfig` включены машинные правила, теперь ломающие сборку при нарушении
|
||||
(`TreatWarningsAsErrors=true`, `EnforceCodeStyleInBuild=true`):
|
||||
- `dotnet_style_qualification_for_{field,property,method,event} = false:warning` — запрет `this.`;
|
||||
- правила именования `IDE1006`: приватные instance-поля `_camelCase`, `const`/`static readonly` — Pascal.
|
||||
|
||||
Также проверено и **не требует правок**: `#region` нет; trailing whitespace нет; все файлы заканчиваются
|
||||
переводом строки; кодировка UTF-8; настоящих public-полей нет (публичные члены — свойства); явные
|
||||
модификаторы доступа соблюдены.
|
||||
|
||||
### Проверка после правок
|
||||
|
||||
- `dotnet build` — `Deal.sln`, `Deal.Telegram.sln`, `Deal.Ai.sln`, `Deal.Ml.sln`: 0 ошибок / 0 предупреждений.
|
||||
- Тесты: core **1275/1275**, telegram **125/125**, ai **52/52**, ml **38/38** — все пройдены.
|
||||
- Повторный прогон renamer: `this.` — 0, полей к переименованию — 0 (идемпотентно).
|
||||
|
||||
## 2. Осталось — требует решения владельца
|
||||
|
||||
1. **`var` — 1529 употреблений.** Правило §4: не использовать для встроенных типов и при неочевидном типе.
|
||||
В `.editorconfig` `csharp_style_var_* = false:silent`. Замена требует семантики (вывод типа).
|
||||
**Рекомендация:** включить анализатор (`:warning`) + `dotnet format` с проверкой.
|
||||
|
||||
2. **Явная реализация интерфейсов (§11).** Субъективное «где возможно» — массовая правка может сломать
|
||||
DI/прямые вызовы и тесты. **Рекомендация:** точечный ревью по 61 интерфейсу, без автоматизации.
|
||||
|
||||
3. **Дедупликация `<summary>` в реализациях через `/// <inheritdoc/>` (§11).** Надёжно детектируется только
|
||||
по семантической модели (сопоставление интерфейс↔класс). В коде уже 674 `<inheritdoc/>`.
|
||||
**Рекомендация:** Roslyn-анализатор, если нужно добить остаток.
|
||||
|
||||
4. **Переводы строк.** `.editorconfig` требует `end_of_line = crlf`, фактически: **231 файл CRLF / 697 LF**
|
||||
(смешанно). Правка объёмная. **Рекомендация:** решить — нормализовать под CRLF или зафиксировать LF.
|
||||
|
||||
## 3. Примечание
|
||||
|
||||
Пункты 2.1, 2.3 можно закрыть анализаторами Roslyn в `Directory.Build.props` — это даст автоматическую
|
||||
проверку на новом коде. Пункт 2.4 — разовое решение по политике переводов строк.
|
||||
# Аудит кода на соответствие код-стайлу «Дейл» (2026-09-11)
|
||||
|
||||
> Отчёт прохода по всему C#-коду (`src/**/*.cs`, 928 файлов, без `bin/obj`).
|
||||
> Правила — `docs/spec/Код-стайл-Дейл.md`. Проверка: сборка 4 решений + все тесты.
|
||||
|
||||
## 1. Исправлено (применено и проверено)
|
||||
|
||||
| Пункт | Правило | Было | Стало | Инструмент |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Блочный `<summary>` | §5 | 5286 однострочных/инлайн (833 файла) | 0 | `scripts/fix_summary_blocks.py --apply` |
|
||||
| XML-док на private/internal | §5 | 2028 блоков (359 файлов) | 0 (понижены до `//`) | `scripts/fix_private_docs.py --apply` |
|
||||
| Квалификация `this.` | §4 | 124 | **0** | разовый Roslyn-инструмент (семантический) |
|
||||
| Приватные instance-поля | §1 | camelCase (`logger`) | `_camelCase` (`_logger`) | разовый Roslyn-инструмент |
|
||||
| Приватные `static readonly`/`const` | §1 | — | Pascal (`DefaultTimeout`) | разовый Roslyn-инструмент |
|
||||
|
||||
Дополнительно в `.editorconfig` включены машинные правила, теперь ломающие сборку при нарушении
|
||||
(`TreatWarningsAsErrors=true`, `EnforceCodeStyleInBuild=true`):
|
||||
- `dotnet_style_qualification_for_{field,property,method,event} = false:warning` — запрет `this.`;
|
||||
- правила именования `IDE1006`: приватные instance-поля `_camelCase`, `const`/`static readonly` — Pascal.
|
||||
|
||||
Также проверено и **не требует правок**: `#region` нет; trailing whitespace нет; все файлы заканчиваются
|
||||
переводом строки; кодировка UTF-8; настоящих public-полей нет (публичные члены — свойства); явные
|
||||
модификаторы доступа соблюдены.
|
||||
|
||||
### Проверка после правок
|
||||
|
||||
- `dotnet build` — `Deal.sln`, `Deal.Telegram.sln`, `Deal.Ai.sln`, `Deal.Ml.sln`: 0 ошибок / 0 предупреждений.
|
||||
- Тесты: core **1275/1275**, telegram **125/125**, ai **52/52**, ml **38/38** — все пройдены.
|
||||
- Повторный прогон renamer: `this.` — 0, полей к переименованию — 0 (идемпотентно).
|
||||
|
||||
## 2. Остатки — решения (закрыто 2026-09-11, вечер)
|
||||
|
||||
1. **`var` — закрыто.** В `.editorconfig` включён ломающий сборку гейт `csharp_style_var_for_built_in_types = false:warning`
|
||||
(запрет только для встроенных типов — как в §4); режимы «очевидный тип» и «прочие» оставлены `silent`
|
||||
осознанно: правка субъективна и потребовала бы ~1600 механических замен. Остаток встроенных типов
|
||||
выправлен `dotnet format style --diagnostics IDE0008` по всем 5 решениям (51 файл); сборка 5 sln — 0/0.
|
||||
2. **Явная реализация интерфейсов (§11) — остаётся точечным ревью владельца.** Замер: 54 интерфейса с XML-doc,
|
||||
из них 43 имеют реализации в src (в основном store-порты с одной реализацией). Массовая правка не
|
||||
автоматизируется сознательно (см. рекомендацию выше).
|
||||
3. **Дедупликация `<summary>` через `<inheritdoc/>` — закрыто: дублей нет.** Проверено двумя независимыми
|
||||
сканами (сопоставление по тексту и по имени члена интерфейса: 39 интерфейсов, 229 задокументированных
|
||||
членов) — реализаций, дублирующих summary интерфейсного члена, в продакшн-коде нет; случаев
|
||||
«`<param>` + дублирующий summary» не существует.
|
||||
4. **Переводы строк — решено: LF.** Обоснование: инструменты проекта (Python/Node-скрипты, codemod'ы) пишут LF;
|
||||
shell-скрипты с CRLF не работают на Linux CI (`sh scripts/ci.sh` в GitHub Actions); фактическое большинство
|
||||
файлов уже было LF. Применено: `.gitattributes` (`* text=auto eol=lf` + бинарные исключения),
|
||||
`.editorconfig` → `end_of_line = lf`, конвертировано 1029 трекаемых файлов, `git add --renormalize`.
|
||||
Побочный эффект: починены 42 CRLF-.sh (9 в `scripts/` — до этого первый удалённый прогон CI падал бы).
|
||||
|
||||
### Попутно исправлено (2026-09-11, вечер)
|
||||
|
||||
- Повторный прогон `scripts/fix_private_docs.py --apply`: понижено 12 XML-доков на private/internal (extension-файлы).
|
||||
- Добавлены недостающие `<summary>`: `IContainerRules.Keywords`/`Stack`, `ITenantContext.TenantId`/`HasTenant`.
|
||||
- Переведены на русский англоязычные `//`-комментарии (3 шт. из 18 найденных; остальные — имена
|
||||
сущностей/заголовки секций тестов, не англоязычный текст).
|
||||
- Из индекса убраны случайно закоммиченные `archive/**/__pycache__/*.pyc` (2 шт., уже в `.gitignore`).
|
||||
- STATUS.md: удалён устаревший блок «Осталось (в backlog)» в шапке (пункты закрытыgeneric-контрактом источника).
|
||||
|
||||
Reference in New Issue
Block a user