О комментариях

(В оригинале - A Comment on Comments)

На самых первых курсах программирования в колледже преподаватель однажды выдал по два бланка «Программа на Basic», написал на доске «Напишите программу, подсчитывающую среднее значение 10 игр в боулинг» и вышел из класса. Было ли это сложно? Я уже не помню деталей, но скорее всего, там был цикл и не более 15 строчек кода. Бланки (да-да, нам приходилось сначала писать программы на бумажных бланках перед тем как вводить их в компьютеры) позволяли написать до 70 строк кода. Мне было непонятно, зачем был нужен второй. Поскольку с аккуратностью у меня были проблемы, я переписал программу на второй бланк максимально аккуратно, надеясь получить дополнительные баллы.

Однако когда я получил проверенный бланк на следующем занятии, я с удивлением обнаружил там весьма мало баллов. Поперек тщательно написанной мной программы красовалась небрежная надпись «Без комментариев?».

То, что и я, и преподаватель знали, что должна делать программа, было недостаточно. Частью обучения была попытка показать, что код должен быть понятным и следующему программисту, пришедшему после меня. И я никогда не забуду этот урок.

Комментарии – это такой же необходимый элемент в программировании, как например условия или циклы. Многие современные языки программирования даже имеют инструмент, позволяющий из специально отформатированных комментариев сгенерировать API документацию. Это очень неплохо, но все же недостаточно. Внутри самого кода должны быть комментарии, объясняющие, что этот код делает. Программирование в стиле «То, что было сложно написать, должно быть не менее сложно прочесть» навредит всем – вашему заказчику, вашему работодателю, коллегам в команде и вам самому в ближайшем будущем.

С другой стороны, не стоит заходить слишком далеко, комментируя все подряд. Комментарии должны прояснять ваш код, а не загромождать его. Лишь немного «сбрызните» код комментариями, объясняющими сложные места. «Заголовочные» комментарии должны предоставлять любому программисту достаточно информации о том, как использовать ваш код, вообще в него не заглядывая. А «внутренние» комментарии должны помочь следующему за вами разработчику сопровождать и изменять ваш код.

На одной своей работе я был несогласен с архитектурным решением, принятым наверху. Испытывая раздражение, часто присущее молодым программистам, я вставил кусок письма с указанием использовать требуемое решение непосредственно в «шапку» файла. Оказалось, что менеджеры просматривали изменения перед каждым коммитом. Так я познакомился со значением термина «действие, ограничивающее карьерный рост».

Автор оригинала - Cal Evans