97 этюдов для программистов. Опыт ведущих экспертов - Пит Гудлиф
В каждом бланке для кода программы — молодым людям, читающим этот текст, поясняю, что мы тогда писали код от руки, прежде чем ввести его в компьютер — было около 70 строк. Мне было совершенно непонятно, почему преподаватель выдал нам по два бланка. Так как почерк у меня всегда был отвратительный, я воспользовался вторым бланком, чтобы аккуратно переписать свой код, надеясь заработать пару очков за стиль.
К большому моему удивлению, получив свою работу обратно на следующем занятии, я обнаружил, что оценка за нее была выставлена чуть выше проходной. (Это стало предзнаменованием всего моего последующего обучения в колледже.) Поверх моего тщательно переписанного кода было выведено: «А комментарии?»
И преподаватель, и я понимали, что делает эта программа, но этого было недостаточно. Часть задачи состояла в том, чтобы научить меня следующему: мой код должен быть понятен другому программисту, который придет после меня. Этот урок я помню до сих пор.
Комментарии — это не порок. Они столь же необходимы в программировании, как основные конструкции ветвлений и циклов. В большинстве современных языков есть средства типа javadoc, которые анализируют написанные в определенном формате комментарии и автоматически составляют справочник по API (интерфейсу прикладного программирования). Иметь такой справочник неплохо, но этого совершенно недостаточно. Код должен содержать пояснения о своем предполагаемом назначении. Когда вы пишете код по древнему принципу «если это было трудно написать, то и читать должно быть не легче», то оказываете медвежью услугу своему клиенту, своему работодателю, своим коллегам, а в будущем и себе.
С другой стороны, не нужно слишком увлекаться комментированием. Следите, чтобы ваши комментарии проясняли код, а не осложняли его чтение. Вставьте в код уместные комментарии, из которых будет ясно, что этот код должен делать. Комментарии в заголовке должны дать любому программисту достаточно информации, чтобы использовать ваш код, не читая его, а комментарии в коде должны помочь тому разработчику, который будет исправлять или расширять код.
На одной моей работе у меня возникло несогласие с проектным решением, принятым «наверху». С язвительной иронией, свойственной молодым программистам, я поместил текст почтового сообщения, содержавшего указания «сверху», в блок комментариев в заголовке файла. Однако оказалось, что менеджеры этой компании лично просматривали код, попадавший в репозиторий. Так я впервые познакомился с термином шаг, стоивший дальнейшей карьеры.
Комментируйте только то, о чем не скажет код
Кевлин Хенни
Расхождение между теорией и практикой на практике больше, чем в теории. Это наблюдение определенно применимо к комментариям. В теории общая идея комментирования кода выглядит достойно: дать читателю детальное объяснение происходящего. Что может быть полезнее, чем давать полезное? А вот на практике комментарии часто вредят. Как и любой вид писательского творчества, написание комментариев требует мастерства. Это мастерство в значительной мере включает в себя понимание того, когда комментарии писать не нужно.
Если код написан с нарушениями синтаксиса, то компиляторы, интерпретаторы и другие средства разработки обязательно воспротивятся. Если код некорректен с функциональной точки зрения, большая часть ошибок выявится в результате рецензирования, статического анализа, тестирования и боевого применения на коммерческом предприятии. А что с комментариями? В книге «The Elements of Programming Style»[7] (Computing McGraw-Hill) Керниган и Плоджер замечают, что «неверный комментарий имеет нулевое или отрицательное значение». И все же такие негодные комментарии успешно приживаются в коде на зависть ошибкам всех видов. Они постоянно отвлекают внимание и дезинформируют. Они служат незаметным, но постоянно действующим тормозом мышления программиста.
Что можно сказать о комментариях, которые формально не являются ошибочными, но не повышают ценности кода? Такие комментарии — просто шум. Иногда комментарии лишь повторяют уже сказанное в коде на естественном языке, то есть попугайничают, не сообщая читателю ничего нового; такое повторение не придает коду ни веса, ни правильности. Закомментированный код не выполняется, поэтому он бесполезен как при чтении кода, так и при его выполнении. Кроме того, он очень быстро устаревает. Комментарии относительно номеров версий и блоки закомментированного кода — это попытки решить вопросы контроля версий и истории кода. Такие вопросы решаются (и гораздо эффективнее) с помощью систем управления версиями.
Засилье в коде бессодержательных и неправильных комментариев провоцирует программистов попросту игнорировать все комментарии, пропуская их при чтении либо выключая их отображение. Программисты — люди изобретательные, и найдут способы обойти все, что покажется им вредоносным: свернут комментарии, изменят цветовую схему так, чтобы комментарии были одного цвета с фоном, или удалят комментарии специально написанным сценарием. Чтобы спасти код от такого неуместного приложения творческих способностей программистов и чтобы снизить риск того, что кто-то пропустит действительно ценные комментарии, следует считать комментарии частью кода. Каждый комментарий должен иметь какую-то ценность для читателя, иначе это просто мусор, который нужно убрать или переработать.
Какой же комментарий можно считать ценным? Только такой комментарий, который сообщает то, чего не говорит и не может сказать код. Если комментарий лишь разъясняет то, что должен самостоятельно сказать фрагмент кода, это указывает на необходимость изменить структуру кода или принятые соглашения по написанию кода, чтобы код говорил за себя сам. Чем комментировать недостаточно точные имена методов и классов, лучше их переименовать. Чем комментировать блоки в длинных функциях, выделите их в маленькие самостоятельные функции, названия которых будут отражать назначения этих блоков. Старайтесь сообщать максимум информации посредством кода. Если вы не можете описать все, что хотелось бы, с помощью одного лишь кода, возможно, тут будет уместен комментарий. Комментируйте то, что не способен сказать код, а не просто то, чего код не говорит.
Непрерывное обучение
Клинт Шэнк
Мы живем в интересные времена. Разработка распределена по всему миру, и, как выясняется, очень многие способны выполнять вашу работу. Чтобы сохранить конкурентоспособность на рынке рабочей силы, нужно непрерывно учиться. Иначе вы превратитесь в динозавра, застрявшего на своем рабочем месте, пока в один прекрасный день не окажется, что вы стали не нужны, или что вашу работу отдали туда, где ее готовы делать дешевле.
Как же решать эту задачу? Одни работодатели не скупятся и организуют обучение, развивающее уже нанятых программистов. Другие вообще не могут
