[Программирование, Анализ и проектирование систем, Проектирование и рефакторинг, IT-стандарты] Хороший, плохой, злой комментарий

Ответить на тему

Автор

Сообщение

news_bot ^®

Стаж: 6 лет 3 месяца
Сообщений: 27286

news_bot ^® написал(а)
03-Апр-2021 09:31

Цитировать

Зачем нужны комментарии, правда ли, что хороший код можно прочитать без них и как перфекционизм замедляет разработку в 4 раза. Новичкам, командам, профи.

"Хороший, плохой, злой", 1966 г.Интуитивное знакомствос комментариями, как и в любых отношениях создаёт скрытые проблемы. Со stackoverflow или от своего творческого начала мы неосознанно формируем манеру комментирования. Кто-то излишне подробную, кто-то с юморком, а кто-то вообще пишет "без комментариев" и через пол года даже не пытается понять, как работает его код. П.С. Если ты тот человек, который узнал о комментариях в коде из книги, дай знак) Если тебе сразу нужны ответы – они в конце.В маленькой веб-студии или в соло-проектах мы сами себе указ и можем писать там хоть анекдоты, вопрос о "технологии" комментирования возникает при переходе к командной разработке, особенно если есть сопровождение продукта. Чтение чужого кода становится не наказанием, а ежедневным занятием... Но сначала и наказанием, пока не наступает момент Х, момент обратиться за знанием.Особенно важно, когда этот момент наступает для целой команды или даже отдела. Ни в коем случае нельзя его упускать – общее стремление исправить ситуацию это шанс, другой момент такого "вскипания" в маленьком проекте может и не наступить, т.к. код копится, как и отчаяние.

Даже в сформированных командах с регламентами и организацией труда, комментирование зачастую интуитивный процесс, чем сознательная часть разработки.

https://shoot-photo.com/desktop-wallpaper-zen.htmlСовершенный код –это перевод названия книги*. Из 950 страниц осмысленного текста, популярность обрела одна фраза: "хороший код является самодокументированным". А к ней пояснения в виде: "хорошему коду не нужны комментарии", "называй переменные и методы понятно, тогда комментарии не нужны".Круто быть столь категоричным, а главное – просто. Но к чему это приводит? Часть превращает комментарии в искусство, стремится к идеалу, размышляет по 20 минут над названиями. Другая часть – формирует чек-листы, правила оформления, требует соблюдения шаблонов. И то, и другое полезно, вот только они забывают о "смысле жизни" комментариев.

Из возможных 20% времени программирования, которые есть у соло-разработчика, в команде остаётся всего 5.

Творчество, точность – всё это очень красиво, когда помогает достичь цель. Понятные имена, комментарии и другие инструменты нужны чтобы снизить неопределенность. В примере выше, 20% времени уделяется программированию и 80% – решению того, что и как программировать, изучению контекста, ТЗ. Это бОльшая часть работы по умолчанию. И чем больше проект, тем ближе к 100% можно "страдать" / "ничего не делать" (нужное подчеркнуть). Чтение даже идеального кода == не программирование.Происходит ситуация, как в поиске по файлам в Win – человек перебирает все файлы, строчки, операции, чтобы найти "то самое" место, где его ждет работа, вместо того, чтобы пробежаться по индексам и через минуту уже выдать новую строчку кода. Вторая функция комментариев – обеспечить быструю навигацию.Всё остальное – лишь форма. Помните о смысле, тогда она будет руслом, а не плотиной из ограничений и бюрократии.*Code Complete, Стив Макконнелл, 1993. Для сохранения смысла точнее будет перевести как "Завершение кода" или "Завершенный код". Комментарии – то, что делает код завершенным, готовым к "эксплуатированию" пользователями, разработчиками, а также обеспечивает комфорт его доработок.ОтветыП.С. По оформлению кода и комментариев есть много руководств, вместо очередного, здесь – тезисы для размышлений.

Существуют разные варианты "использования" кода и комментарии для них отличаются.
- Подключение по типу "черный ящик" – пользователя интересует только что на входе/выходе. Обычно в виде шапки в файле класса и около методов. Хорошо указывать в шапке дату актуализации, перечень методов (содержание). Идеальное использование: за минуту прочитал и пользуешься.
- Открытая библиотека – возможны большие комментарии с описанием принципов, данных, нюансов конкретных решений в коде. Пол часика почитал, пользуешься, в процессе изучаешь дальше.
- Разработка – комментарии в коде, короткие, описывающие этапы, группы/блоки операций, а так же комментарии вида TODO (сделать), FIX (исправить) и т.д. Они не дублируют код, а иллюстрируют, как краткое содержание параграфов. В идеале: посмотрел шапку, пробежался по описаниям и нашел нужное место за пару минут – работаешь.
Неопределенность и навигация. Можно прочитать 10 000 строк идеального кода, понять его и исправить 3 строчки. Хорошие комментарии – те, что позволят сделать это "сразу", а не к обеду. Плюсом будет документирование архитектуры (хотя бы), но это другая история.
Красота – единообразие не только красиво, но и понятно. Привычное быстрее воспринимается. Определите удобные для себя правила оформления в команде.
Шаблоны – упрощают жизнь, но без фанатизма, у функций бывают необязательные параметры.
Незавершенность – буквально. Пока код используется - он не завершен. Не относитесь к нему, как к памятнику, "камню, из которого убрали всё лишнее". Искусственные блоки для кода, лишние строки для визуального отделения, рабочие комментарии, идеи... Всё это может быть, если оно соответствует духу вашей команды.

На этом у меня всё, успехов!П.С. Буду рад дополнить статью идеями из... комментариев.
===========
Источник:
habr.com
===========
Похожие новости:

Теги для поиска: #_programmirovanie (Программирование), #_analiz_i_proektirovanie_sistem (Анализ и проектирование систем), #_proektirovanie_i_refaktoring (Проектирование и рефакторинг), #_itstandarty (IT-стандарты), #_kommentirovanie_koda (комментирование кода), #_dokumentirovanie (документирование), #_kodrevju (код-ревью), #_programmirovanie (
Программирование
), #_analiz_i_proektirovanie_sistem (
Анализ и проектирование систем
), #_proektirovanie_i_refaktoring (
Проектирование и рефакторинг
), #_itstandarty (
IT-стандарты
)

Профиль ЛС

Ответить на тему

Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы

Текущее время: 15-Май 11:45
Часовой пояс: UTC + 5