Зачем нужны комментарии, правда ли, что хороший код можно прочитать и без них и как перфекционизм замедляет разработку в 4 раза.
Новички, команды, профессионалы.
«Хороший, плохой, злой», 1966 г.
Интуитивные знакомства
комментарии, как и в любых отношениях, создают скрытые проблемы.Из stackoverflow или своего творчества мы неосознанно формируем стиль комментирования.
Некоторые излишне подробные, некоторые с юмором, третьи пишут «без комментариев» и через полгода даже не пытаются понять, как работает их код. P.S. Если вы тот человек, который узнал о комментариях в коде из книги, дайте знак) Если вам нужны ответы сразу, то они в конце.
В небольшой веб-студии или в сольных проектах мы сами себе указываем и можем там даже шутки писать; вопрос о «технологии» комментирования возникает при переходе к командной разработке, особенно если есть поддержка продукта.
Чтение чужого кода становится не наказанием, а ежедневным занятием.
Но сначала это тоже наказание, пока не наступит момент Х, момент поиска знаний .
Это особенно важно, когда этот момент наступает для всей команды или даже отдела.
Ни при каких обстоятельствах нельзя его упускать – это шанс коллективно изменить ситуацию к лучшему; очередной момент такого «кипения» в небольшом проекте может и не наступить, т.к.
код накапливается, как и отчаяние.
Даже в устоявшихся командах с регламентом и организацией работы комментирование зачастую является интуитивным процессом, а не сознательной частью разработки.
https://shoot-photo.com/desktop-wallpaper-zen.html
Идеальный код -
это перевод названия книги * .Из 950 страниц осмысленного текста популярность приобрела одна фраза: " хороший код самодокументируется И этому есть пояснения в виде: «хороший код не нуждается в комментариях», «понятно называйте переменные и методы, тогда комментарии не нужны».
Круто быть таким категоричным, а главное просто.
Но к чему это приводит? Часть превращает комментарии в искусство, стремится к идеалу и 20 минут размышляет над заголовками.
Другая часть — создание контрольных списков, правил дизайна и требование соблюдения шаблонов.
Оба полезны, но забывают о «смысле жизни» комментариев.
Из возможных 20% времени программирования, которыми располагает одиночный разработчик, в команде остается только 5.Креативность и точность – это очень красиво, но когда они помогают достичь цели.
Четкие названия, комментарии и другие инструменты необходимы для уменьшить неопределенность .
В приведенном выше примере 20% времени уходит на программирование и 80% на решение, что и как программировать, изучение контекста, технических характеристик.
Это большая часть работы, выполняемая по умолчанию.
И чем масштабнее проект, тем ближе к 100% можно «терпеть»/ «ничего не делать» (нужное подчеркнуть).
Чтение даже идеального кода == не программирование.
Возникает ситуация как при поиске по файлам в Win - человек перебирает все файлы, строки, операции, чтобы найти "то самое" место, где его ждет работа, вместо того, чтобы перебирать индексы и через минуту выдавать новую строчку кода .
Вторая функция комментариев обеспечить быструю навигацию .
Все остальное — всего лишь форма.
Помните смысл, тогда это будет канал, а не плотина ограничений и бюрократии.
* Код завершен, Стив МакКоннелл, 1993. Чтобы сохранить смысл, правильнее было бы перевести как «Завершение кода» или «Завершенный код».
Комментарии — это то, что делает код законченным, готовым к «эксплуатации» пользователями и разработчиками, а также обеспечивает комфортность его модификаций.
Ответы
P.S. Существует множество руководств по форматированию кода и комментариев; вместо еще одного, вот несколько моментов для размышления.
- Есть разные способы «использования» кода и комментарии к ним разные.
- Подключение к «черному ящику» — пользователя интересует только то, что находится на входе/выходе.
Обычно в виде заголовка в файле класса и рядом с методами.
Хорошо в шапке указать дату обновления и список методов (контента).
Идеальное использование: прочтите и используйте за минуту.
- Открытая библиотека — возможны большие комментарии с описанием принципов, данных и нюансов конкретных решений в коде.
Я читаю его полчаса, использую и учусь дальше в процессе.
- Разработка — комментарии в коде короткие, описывающие этапы, группы/блоки операций, а также комментарии типа TODO (сделать), FIX (исправить) и т.п.
Они не дублируют код, а иллюстрируют его как краткое изложение пунктов.
.
В идеале: посмотрите шапку, пройдитесь по описаниям и за пару минут найдите нужное место — вы работаете.
- Подключение к «черному ящику» — пользователя интересует только то, что находится на входе/выходе.
- Неопределенность и навигация .
Вы можете прочитать 10 000 строк идеального кода, понять его и исправить 3 строчки.
Хорошие комментарии — те, которые позволяют сделать это «сразу», а не к обеду.
Документирование архитектуры (по крайней мере) было бы плюсом, но это уже другая история.
- красота – Однообразие – это не только красиво, но и понятно.
Привычное воспринимается быстрее.
Определите удобные для вас правила построения команды.
- Шаблоны — облегчают жизнь, но без фанатизма, функции имеют необязательные параметры.
- незавершенность - буквально.
Пока код используется, он не является полным.
Не относитесь к нему как к памятнику, «камню, из которого удалено все ненужное».
Искусственные блоки для кода, дополнительные строки для визуального разделения, рабочие комментарии, идеи… Все это может случиться, если соответствует духу вашей команды.
комментариев.
В опросе могут участвовать только зарегистрированные пользователи.
Войти , Пожалуйста.
Комментирую.
68,33% от души =) 41 31,67% по регламенту/шаблонам и вообще как надо 19 проголосовали 60 пользователей.
24 пользователя воздержались.
Теги: #программирование #Анализ и проектирование систем #ИТ-стандарты #проектирование и рефакторинг #ревью кода #документация #комментирование кода
-
Обзор О Toshiba Portege-R700-18D
19 Oct, 24 -
Конго
19 Oct, 24 -
Распределяем Нагрузку В Зависимости От Url
19 Oct, 24 -
Загрузить Новый Медиа-Файл С Url-Адреса
19 Oct, 24 -
Почему Php Устарел
19 Oct, 24 -
Алгоритм Построения Покрывающих Множеств
19 Oct, 24
