16/97: Комментарий о комментариях

Это перевод A Comment on Comments. Автор: Cal Evans.

Из "97-ми вещей, которые должен знать каждый программист".

На моём первом занятии по программированию в колледже мой учитель дал мне два бланка для написания программы на BASIC-е. На доске он написал: "Напишите программу, которая читает и считает среднее между 10-ю играми в боулинг". Потом он вышел из класса. Ну, насколько сложным это может быть? Я не помню своё решение, но я уверен, что там был цикл FOR/NEXT и там было не более 15 строк кода. Бланки (для школоты: да, раньше мы писали программы от руки на бланках, прежде чем вводить их в компьютер) допускали 70 строк кода на каждом. Я был озадачен, зачем учитель дал мне два бланка. Ну, поскольку с аккуратностью у меня были проблемы, то я максимально аккуратно переписал программу на второй бланк, надеясь получить дополнительные баллы за стиль.

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

Для учителя было недостаточно, что он и я знали, что должна делать эта программа. Частью этого задания было научить меня, что мой код должен объяснять сам себя для программиста, который придёт после меня. Это урок, который я никогда не забуду.

Комментарии - это не зло. Они являются неотъемлемой частью кода - как и циклы. Многие современные средства разработки имеют утилиты типа javadoc, который создают файл справки API по комментариям, отформатированных особым образом. Это хорошее начало, но этого недостаточно. В самом вашем коде должны быть объяснения, что должен делать этот код. Кодирование в стиле "это было тяжело написать - так что это должно тяжело читаться" оказывают плохую службы вашему клиенту, вашему работодателю и вам самим, несколько месяцев спустя.

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

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