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

Интуитивное знакомство

с комментариями как и в любых отношениях создаёт скрытые проблемы. Со stackoverflow или от своего творческого начала мы неосознанно формируем манеру комментирования. Кто-то излишне подробную, кто-то с юморком, а кто-то вообще пишет "без комментариев" и через пол года даже не пытается понять, как работает его код.

П.С. Если ты тот человек, который узнал о комментариях в коде из книги, дай знак) Если тебе сразу нужны ответы – они в конце.

В маленькой веб-студии или в соло-проектах мы сами себе указ и можем писать там хоть анекдоты, вопрос о "технологии" комментирования возникает при переходе к командной разработке, особенно если есть сопровождение продукта. Чтение чужого кода становится не наказанием, а ежедневным занятием... Но сначала и наказанием, пока не наступает момент Х, момент обратиться за знанием.

Особенно важно, когда этот момент наступает для целой команды или даже отдела. Ни в коем случае нельзя его упускать – это шанс дружно изменить ситуацию к лучшему, другой момент такого "вскипания" в маленьком проекте может и не наступить, т.к. код копится, как и отчаяние.

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

Совершенный код –

это перевод названия книги*. Из 950 страниц осмысленного текста, популярность обрела одна фраза: "хороший код является самодокументированным". А к ней пояснения в виде: "хорошему коду не нужны комментарии", "называй переменные и методы понятно, тогда комментарии не нужны".

Круто быть столь категоричным, а главное – просто. Но к чему это приводит? Часть превращает комментарии в искусство, стремится к идеалу, размышляет по 20 минут над названиями. Другая часть – формирует чек-листы, правила оформления, требует соблюдения шаблонов. И то, и другое полезно, вот только они забывают о "смысле жизни" комментариев.

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

Творчество и точность – это очень красиво, но когда помогает достичь цель. Понятные имена, комментарии и другие инструменты нужны чтобы снизить неопределенность.

В примере выше, 20% времени уделяется программированию и 80% – решению того, что и как программировать, изучению контекста, ТЗ. Это бОльшая часть работы по умолчанию. И чем больше проект, тем ближе к 100% можно "страдать" / "ничего не делать" (нужное подчеркнуть). Чтение даже идеального кода == не программирование.

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

Всё остальное – лишь форма. Помните о смысле, тогда она будет руслом, а не плотиной из ограничений и бюрократии.

*Code Complete, Стив Макконнелл, 1993. Для сохранения смысла точнее будет перевести как "Завершение кода" или "Завершенный код". Комментарии – то, что делает код завершенным, готовым к "эксплуатированию" пользователями, разработчиками, а также обеспечивает комфорт его доработок.

Ответы

П.С. По оформлению кода и комментариев есть много руководств, вместо очередного, здесь – тезисы для размышлений.

1. Существуют разные варианты "использования" кода и комментарии для них отличаются.

   1. Подключение по типу "чёрный ящик" – пользователя интересует только что на входе/выходе. Обычно в виде шапки в файле класса и около методов. Хорошо указывать в шапке дату актуализации, перечень методов (содержание). Идеальное использование: за минуту прочитал и пользуешься.

   2. Открытая библиотека – возможны большие комментарии с описанием принципов, данных, нюансов конкретных решений в коде. Пол часика почитал, пользуешься, в процессе изучаешь дальше.

   3. Разработка – комментарии в коде, короткие, описывающие этапы, группы/блоки операций, а так же комментарии вида TODO (сделать), FIX (исправить) и т.д. Они не дублируют код, а иллюстрируют, как краткое содержание параграфов. В идеале: посмотрел шапку, пробежался по описаниям и нашел нужное место за пару минут – работаешь.

2. Неопределенность и навигация. Можно прочитать 10 000 строк идеального кода, понять его и исправить 3 строчки. Хорошие комментарии – те, что позволят сделать это "сразу", а не к обеду. Плюсом будет документирование архитектуры (хотя бы), но это другая история.

3. Красота – единообразие не только красиво, но и понятно. Привычное быстрее воспринимается. Определите удобные для себя правила оформления в команде.

4. Шаблоны – упрощают жизнь, но без фанатизма, у функций бывают необязательные параметры.

5. Незавершенность – буквально. Пока код используется - он не завершен. Не относитесь к нему, как к памятнику, "камню, из которого убрали всё лишнее". Искусственные блоки для кода, лишние строки для визуального отделения, рабочие комментарии, идеи... Всё это может быть, если оно соответствует духу вашей команды.

На этом у меня всё, успехов!

П.С. Буду рад дополнить статью идеями из... комментариев.