97 этюдов для программистов. Опыт ведущих экспертов

Комментарий о комментариях Кэл Эванс

На моем первом занятии по программированию в колледже преподаватель выдал нам по два бланка для составления текста программы на BASIC. На доске он написал задание: «Составить программу для ввода и вычисления среднего из 10 результатов в боулинге». Затем преподаватель вышел из комнаты. Трудна ли эта задача? Не помню своего решения, но, кажется, там был цикл FOR/NEXT и не более 15 строк кода.

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

К большому моему удивлению, получив свою работу обратно на следующем занятии, я обнаружил, что оценка за нее была выставлена чуть выше проходной. (Это стало предзнаменованием всего моего последующего обучения в колледже.) Поверх моего тщательно переписанного кода было выведено: «А комментарии?»

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

Комментарии — это не порок. Они столь же необходимы в программировании, как основные конструкции ветвлений и циклов. В большинстве современных языков есть средства типа javadoc, которые анализируют написанные в определенном формате комментарии и автоматически составляют справочник по API (интерфейсу прикладного программирования). Иметь такой справочник неплохо, но этого совершенно недостаточно. Код должен содержать пояснения о своем предполагаемом назначении. Когда вы пишете код по древнему принципу «если это было трудно написать, то и читать должно быть не легче», то оказываете медвежью услугу своему клиенту, своему работодателю, своим коллегам, а в будущем и себе.

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

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