Зачем нужны комментарии, правда ли, что хороший код можно прочитать без них и как перфекционизм замедляет разработку в 4 раза. Новичкам, командам, профи.
Интуитивное знакомство
с комментариями как и в любых отношениях создаёт скрытые проблемы. Со stackoverflow или от своего творческого начала мы неосознанно формируем манеру комментирования. Кто-то излишне подробную, кто-то с юморком, а кто-то вообще пишет "без комментариев" и через пол года даже не пытается понять, как работает его код.
П.С. Если ты тот человек, который узнал о комментариях в коде из книги, дай знак) Если тебе сразу нужны ответы – они в конце.
В маленькой веб-студии или в соло-проектах мы сами себе указ и можем писать там хоть анекдоты, вопрос о "технологии" комментирования возникает при переходе к командной разработке, особенно если есть сопровождение продукта. Чтение чужого кода становится не наказанием, а ежедневным занятием... Но сначала и наказанием, пока не наступает момент Х, момент обратиться за знанием.
Особенно важно, когда этот момент наступает для целой команды или даже отдела. Ни в коем случае нельзя его упускать – это шанс дружно изменить ситуацию к лучшему, другой момент такого "вскипания" в маленьком проекте может и не наступить, т.к. код копится, как и отчаяние.
Даже в сформированных командах с регламентами и организацией труда, комментирование зачастую интуитивный процесс, чем сознательная часть разработки.
Совершенный код –
это перевод названия книги*. Из 950 страниц осмысленного текста, популярность обрела одна фраза: "хороший код является самодокументированным". А к ней пояснения в виде: "хорошему коду не нужны комментарии", "называй переменные и методы понятно, тогда комментарии не нужны".
Круто быть столь категоричным, а главное – просто. Но к чему это приводит? Часть превращает комментарии в искусство, стремится к идеалу, размышляет по 20 минут над названиями. Другая часть – формирует чек-листы, правила оформления, требует соблюдения шаблонов. И то, и другое полезно, вот только они забывают о "смысле жизни" комментариев.
Из возможных 20% времени программирования, которые есть у соло-разработчика, в команде остаётся всего 5.
Творчество и точность – это очень красиво, но когда помогает достичь цель. Понятные имена, комментарии и другие инструменты нужны чтобы снизить неопределенность.
В примере выше, 20% времени уделяется программированию и 80% – решению того, что и как программировать, изучению контекста, ТЗ. Это бОльшая часть работы по умолчанию. И чем больше проект, тем ближе к 100% можно "страдать" / "ничего не делать" (нужное подчеркнуть). Чтение даже идеального кода == не программирование.
Происходит ситуация, как в поиске по файлам в Win – человек перебирает все файлы, строчки, операции, чтобы найти "то самое" место, где его ждет работа, вместо того, чтобы пробежаться по индексам и через минуту уже выдать новую строчку кода. Вторая функция комментариев – обеспечить быструю навигацию.
Всё остальное – лишь форма. Помните о смысле, тогда она будет руслом, а не плотиной из ограничений и бюрократии.
*Code Complete, Стив Макконнелл, 1993. Для сохранения смысла точнее будет перевести как "Завершение кода" или "Завершенный код". Комментарии – то, что делает код завершенным, готовым к "эксплуатированию" пользователями, разработчиками, а также обеспечивает комфорт его доработок.
Ответы
П.С. По оформлению кода и комментариев есть много руководств, вместо очередного, здесь – тезисы для размышлений.
Существуют разные варианты "использования" кода и комментарии для них отличаются.
Подключение по типу "чёрный ящик" – пользователя интересует только что на входе/выходе. Обычно в виде шапки в файле класса и около методов. Хорошо указывать в шапке дату актуализации, перечень методов (содержание). Идеальное использование: за минуту прочитал и пользуешься.
Открытая библиотека – возможны большие комментарии с описанием принципов, данных, нюансов конкретных решений в коде. Пол часика почитал, пользуешься, в процессе изучаешь дальше.
Разработка – комментарии в коде, короткие, описывающие этапы, группы/блоки операций, а так же комментарии вида TODO (сделать), FIX (исправить) и т.д. Они не дублируют код, а иллюстрируют, как краткое содержание параграфов. В идеале: посмотрел шапку, пробежался по описаниям и нашел нужное место за пару минут – работаешь.
Неопределенность и навигация. Можно прочитать 10 000 строк идеального кода, понять его и исправить 3 строчки. Хорошие комментарии – те, что позволят сделать это "сразу", а не к обеду. Плюсом будет документирование архитектуры (хотя бы), но это другая история.
Красота – единообразие не только красиво, но и понятно. Привычное быстрее воспринимается. Определите удобные для себя правила оформления в команде.
Шаблоны – упрощают жизнь, но без фанатизма, у функций бывают необязательные параметры.
Незавершенность – буквально. Пока код используется - он не завершен. Не относитесь к нему, как к памятнику, "камню, из которого убрали всё лишнее". Искусственные блоки для кода, лишние строки для визуального отделения, рабочие комментарии, идеи... Всё это может быть, если оно соответствует духу вашей команды.
На этом у меня всё, успехов!
П.С. Буду рад дополнить статью идеями из... комментариев.
