65 lines
4.2 KiB
Markdown
65 lines
4.2 KiB
Markdown
# Спорные кандидаты на удаление комментариев
|
|
|
|
Дата создания: 2026-04-29.
|
|
|
|
Назначение файла:
|
|
- фиксировать комментарии, которые могут подпадать под удаление по исходному заданию
|
|
- не размечать эти места внутри исходников новыми `TODO`
|
|
- оставить возможность позже быстро пройтись и удалить их одним отдельным этапом, если будет подтверждение
|
|
|
|
## Статус правила
|
|
|
|
- явный закомментированный код и debug-хвосты удаляются сразу
|
|
- спорные смысловые комментарии временно оставляются в коде
|
|
- кандидаты на последующее удаление записываются сюда
|
|
|
|
## Кандидаты
|
|
|
|
### 1. `v1/resources/instance_operation_default.cfc`
|
|
|
|
Оставлены пока что:
|
|
- комментарий про получение параметров из свежего стейта
|
|
- комментарии вокруг `formatter`, `value_list`, `default_compute`, `nested_ref_data`
|
|
- комментарии о частичном дублировании и временности некоторых решений
|
|
|
|
Почему спорно:
|
|
- часть комментариев выглядит как внутренние рассуждения автора
|
|
- часть при этом все еще помогает понять, зачем код делает нетривиальные вещи
|
|
|
|
Рекомендация:
|
|
- при отдельном подтвержденном этапе можно удалить большую часть комментариев-оценок и оставить только технические пояснения к формату данных
|
|
|
|
### 2. `v1/resources/instance_default.cfc`
|
|
|
|
Оставлены пока что:
|
|
- технические комментарии вокруг структуры шаблона экземпляра и вызова генерации имени
|
|
|
|
Почему спорно:
|
|
- часть уже очищена, остаток невелик и не мешает, но при строгом чтении задания может быть сокращен еще сильнее
|
|
|
|
Рекомендация:
|
|
- если потребуется максимально сухой код, пройтись повторно и убрать остаточные пояснения, не влияющие на понимание API-контракта
|
|
|
|
### 3. `v1/resources/notification_ls.cfc`
|
|
|
|
Оставлены пока что:
|
|
- короткие технические комментарии про фильтрацию и сортировку
|
|
|
|
Почему спорно:
|
|
- они не являются рассуждениями, но при очень агрессивной зачистке тоже могут считаться лишними
|
|
|
|
Рекомендация:
|
|
- удалять только если решено доводить list-resource до почти полного отсутствия комментариев
|
|
|
|
### 4. `v1/resources/instance_operation_cfs_param_ls.cfc`
|
|
|
|
После частичной зачистки в файле все еще оставлены:
|
|
- комментарии по смыслу валидации, уникальности и ограничениям параметров
|
|
- часть пояснений к SQL-условиям и поведению проверок
|
|
|
|
Почему вынесено заранее:
|
|
- файл крупный и неоднозначный
|
|
- лучше разбирать отдельным этапом, чем смешивать с обычной зачисткой компактных ресурсов
|
|
|
|
Рекомендация:
|
|
- если потребуется более жесткая зачистка, пройтись по оставшимся поясняющим комментариям отдельно и удалить те, которые не нужны для понимания правил валидации |