cleanup: remove reasoning comments and translate helper docs

2026-04-29 20:51:44 +04:00
parent f6d5c868cb
commit 7b98eee156
6 changed files with 145 additions and 161 deletions
@@ -312,3 +312,94 @@
 - сделать второй проход по прикладным файлам
 - удалить комментарии в формате рассуждений там, где они явно не нужны для понимания текущей логики
 - отдельно обработать `v1/Application.cfc` как специальный случай
+
+## Обновление: второй проход по комментариям-рассуждениям
+
+Дата фиксации: 2026-04-29 20:45:13 +0400.
+
+### Что сделано
+
+Во втором проходе очищались не version-header блоки, а именно комментарии в стиле внутренних сомнений, оценок и рассуждений автора.
+
+Обработаны файлы:
+- `v1/lib/field_set.cfm`
+- `v1/lib/order_build.cfm`
+- `v1/resources/svc_default.cfc`
+- `v1/lib/rest_api_helper.cfc`
+
+Удалялись в первую очередь такие типы комментариев:
+- сомнения автора в корректности подхода
+- эмоциональные оценки вроде "некрасиво"
+- внутренние заметки вида "не уверен", "не нравится", "странно"
+- краткие следы от отладочных/временных рассуждений
+
+### Что не удалялось
+
+- технические комментарии, поясняющие назначение параметров и смысл структуры данных
+- комментарии, нужные для понимания формата вызова или ограничений API
+- комментарии, которые пока относятся к будущему этапу перевода, а не удаления
+
+### Проверка
+
+После второго прохода измененные файлы проверены на ошибки.
+Результат:
+- синтаксических ошибок не обнаружено
+
+### Промежуточный вывод
+
+Эта стратегия работает лучше, чем агрессивная массовая чистка: можно постепенно отделять лишние авторские рассуждения от реально полезных технических пояснений.
+
+### Следующий шаг
+
+- перевести оставшиеся английские комментарии в уже обработанных небольших файлах
+- отдельно обработать `v1/lib/TokenGenerator.cfc`, где комментарии почти полностью англоязычные
+- затем перейти к следующей группе прикладных файлов
+
+## Обновление: дополнительные commented-out блоки и перевод комментариев
+
+Дата фиксации: 2026-04-29 20:48:58 +0400.
+
+### Что сделано перед переводом
+
+Перед этапом перевода был выполнен еще один безопасный шаг:
+- удалены крупные закомментированные legacy-блоки в `v1/lib/rest_api_helper.cfc`
+- удален закомментированный альтернативный блок base64url-преобразования в `v1/lib/TokenGenerator.cfc`
+
+Причина:
+- переводить комментарии вокруг уже неиспользуемого мертвого кода не имеет смысла
+- сначала убирается то, что точно не участвует в runtime
+
+### Что переведено на русский
+
+Перевод выполнен в следующих файлах:
+- `v1/lib/TokenGenerator.cfc`
+- `v1/lib/field.cfm`
+- `v1/lib/order_build.cfm`
+- `v1/lib/filter_build.cfm`
+- `v1/lib/rest_api_helper.cfc`
+
+Переводились:
+- `hint`-описания функций и компонентов
+- английские технические комментарии
+- внутренние пояснения о поведении генератора токенов и helper-логики
+
+Что сознательно не переводилось:
+- runtime-сообщения ошибок и исключений
+- публичные текстовые значения, которые могут участвовать в API-контракте
+
+### Проверка
+
+После удаления закомментированных блоков и после перевода комментариев проверены измененные файлы.
+Результат:
+- синтаксических ошибок не обнаружено
+
+### Промежуточный вывод
+
+На этом этапе уже очищен и приведен к более однородному виду значимый кусок вспомогательного слоя `v1/lib`.
+Это хорошая база перед переходом к более рискованным файлам уровня `Application.cfc` и крупных `resources/*.cfc`.
+
+### Следующий шаг
+
+- посмотреть текущее diff-состояние cleanup-ветки
+- зафиксировать сделанные этапы в коммитах
+- затем перейти к следующей группе файлов, начиная с наиболее контролируемых resource-компонентов