31 мая 2007 года аукнулось. Возмущенная серией самодержавных банов толпа распяла своего создателя, понизив ему карму до −2. Крючков обиделся и выставил себе ∞.
Комментарии (9)
NightShad0w
16.12.2021 00:18+3Не стоит плодить сущности без необходимости. Документация, живущая отдельно от документируемой сущности, становится неактуальной сразу после написания.
Без автоматической системы проверки согласованности внешняя документация отъедет от кода на следующем же дедлайне. TDD — хотя бы на компилятор\интерпретатор полагается, что все равно не решает проблему человеческого фактора. Если тесты стали красные, а менеджер говорит выкатываем, потому что контракты и обязательства, тесты будут отключены или проигнорированы.
mSnus
16.12.2021 08:35+8Хороший код очень часто понятен без комментариев
-
Ваши комментарии зачастую длиннее, чем сам код:
foreach ($sections as & $section) {
// #2 обслуживание разделов каталога
И довольно бесполезны - не, обслуживание разделов каталога, а так это неясно? Назовите переменную $catalogueSections, точно будет ясно и без комментариев
Надо каждым комментарием у вас ещё и надо задумываться, это #2 или #3? #ВЕ или #ВА? Это такое метапрограммирование, поэтому общее количество кода удваивается
Поэтому держать в голове или перед глазами блок кода получается сложнее -- вместо слитной "речи" получается разбиение на отдельные слова. Как. Будто. Вы. Так. Всё. Пишете. Неудобно.
Поэтому уверен - никто подобным добровольно заниматься не будет. А если заставлять - будут увольняться.
kesn
16.12.2021 10:31+3Короче, идея: пишите всю вашу метаинфу в сообщении к коммиту. А потом git blame, и вот вам аннотация к строчкам, забесплатно.
napa3um
16.12.2021 12:57+1По сути дела да, автор изобрёл неприменимую, гиперусложнённую конвенцию commit-сообщений (только пока без инструментов контроля изменений и версионирования кода). Автор хочет в коде подстрочный дубляж с мотивами внесения в репозиторий каждой строчки. Но будто в каком-то абстрактном, оторванном от конкретики проекта виде.
napa3um
Да, идея простая и наивная - заставить программистов писать комментарии к своему коду. Но подобной (абсолютно беспредметной) бюрократией с этими всеми пунктами-подпунктами и слоями-подслоями проблема не решается, такова жизнь. И она именно такова, с ленивыми программистами, решающими прикладные задачи менеджеров, а не религиозные обряды комментарных евангелистов :).
Одна из более-менее рабочих методологий, заставляющая писать требования к коду до написания кода, - TDD. Ну и вообще, дизайн тестировочных фреймворков многое формализует и решает в задачах синхронного ведения кодовой базы и формальных требований к ней. А также вопросы (само)документируемости кода решает прозрачность архитектуры, когда назначение кода понятно не только из имён переменных в нём или комментариев, но и из того, где он расположен в иерархии модулей. И ещё очень полезно аккуратно заполнять поля и связи задач в Jira, привязывая их и к коммитам в репозитории. В общем, без организации процесса (с обратной связью для возможности улучшений) никакие благие намерения не будут работать, даже с таким подробным классификатором :).
lysenkoan Автор
хм .. звучит странно, причем тут ленивые и заставлять? Я буду пользоваться, культурные разработчики тоже, профессионалы тоже, люди, уважающие свой труд тоже, компании, подряжающие команды, тоже, компании, уставшие от legacy-систем тоже ... Писать 2 недели код и не потратить 40 минут, чтобы его описать и потом улучшать - ну это особый вид профессионального самоубийства.
napa3um
Никто не будет, скорее всего. И не потому что они плохие, непрофессиональные, неуважающие и так далее. А потому что это не принесёт пользы, сравнимой с затратами на эти интеллектуальные упражнения (по формулированию комментариев для посторонних людей). Поддерживать иерархию совершенно абстрактных требований ради религиозной веры в Светлое и Прекрасное никто не станет, ибо код - это не есть конечная цель разработки (в большинстве проектов), а лишь временное отражение текущего решения, и для кода, скорее, более важной характеристикой является его подвижность (оперативность внесения изменений под новые бизнес-требования), ежели его статичная изучаемость непогружённым автономным программистом. Пока вы будете писать комментарии по подобной сложной схеме, код успеет умереть пару раз. Отрасль уже давно живёт импульсивными аджайлами, а не вековыми гостами. (Это всё моё субъективное, конечно, и слегка утрированное мнение :))
lysenkoan Автор
смешно
lair
Я — культурный разработчик, профессионал, и я не буду пользоваться описанной в посте системой.