• В общем случае каждая единица кода, начиная с фрагмента и заканчивая целой библиотекой, должна иметь ограниченный интерфейс. Сокращение потока информации упрощает доказательство. Это означает, что следует избегать методов, возвращающих внутреннее состояние (getters). Нужно не запрашивать у объекта информацию для обработки, а требовать, чтобы он выполнил работу с той информацией, которая у него уже есть. Иными словами, инкапсуляция — это ограниченные интерфейсы, и только они.
• Чтобы сохранить инварианты класса, следует избегать методов, присваивающих значения (setters). Они часто влекут нарушение инвариантов, определяющих состояния объекта.
Доказательство корректности кода, как и его обсуждение, позволит вам лучше в нем разобраться. Сообщайте о своих открытиях — это пойдет всем на пользу.
Комментарий о комментариях
Кэл Эванс
На моем первом занятии по программированию в колледже преподаватель выдал нам по два бланка для составления текста программы на BASIC. На доске он написал задание: «Составить программу для ввода и вычисления среднего из 10 результатов в боулинге». Затем преподаватель вышел из комнаты. Трудна ли эта задача? Не помню своего решения, но, кажется, там был цикл FOR/NEXT и не более 15 строк кода.
В каждом бланке для кода программы — молодым людям, читающим этот текст, поясняю, что мы тогда писали код от руки, прежде чем ввести его в компьютер — было около 70 строк. Мне было совершенно непонятно, почему преподаватель выдал нам по два бланка. Так как почерк у меня всегда был отвратительный, я воспользовался вторым бланком, чтобы аккуратно переписать свой код, надеясь заработать пару очков за стиль.
К большому моему удивлению, получив свою работу обратно на следующем занятии, я обнаружил, что оценка за нее была выставлена чуть выше проходной. (Это стало предзнаменованием всего моего последующего обучения в колледже.) Поверх моего тщательно переписанного кода было выведено: «А комментарии?»
И преподаватель, и я понимали, что делает эта программа, но этого было недостаточно. Часть задачи состояла в том, чтобы научить меня следующему: мой код должен быть понятен другому программисту, который придет после меня. Этот урок я помню до сих пор.
Комментарии — это не порок. Они столь же необходимы в программировании, как основные конструкции ветвлений и циклов. В большинстве современных языков есть средства типа javadoc, которые анализируют написанные в определенном формате комментарии и автоматически составляют справочник по API (интерфейсу прикладного программирования). Иметь такой справочник неплохо, но этого совершенно недостаточно. Код должен содержать пояснения о своем предполагаемом назначении. Когда вы пишете код по древнему принципу «если это было трудно написать, то и читать должно быть не легче», то оказываете медвежью услугу своему клиенту, своему работодателю, своим коллегам, а в будущем и себе.
С другой стороны, не нужно слишком увлекаться комментированием. Следите, чтобы ваши комментарии проясняли код, а не осложняли его чтение. Вставьте в код уместные комментарии, из которых будет ясно, что этот код должен делать. Комментарии в заголовке должны дать любому программисту достаточно информации, чтобы использовать ваш код, не читая его, а комментарии в коде должны помочь тому разработчику, который будет исправлять или расширять код.
На одной моей работе у меня возникло несогласие с проектным решением, принятым «наверху». С язвительной иронией, свойственной молодым программистам, я поместил текст почтового сообщения, содержавшего указания «сверху», в блок комментариев в заголовке файла. Однако оказалось, что менеджеры этой компании лично просматривали код, попадавший в репозиторий. Так я впервые познакомился с термином шаг, стоивший дальнейшей карьеры.
Комментируйте только то, о чем не скажет код
Кевлин Хенни
Расхождение между теорией и практикой на практике больше, чем в теории. Это наблюдение определенно применимо к комментариям. В теории общая идея комментирования кода выглядит достойно: дать читателю детальное объяснение происходящего. Что может быть полезнее, чем давать полезное? А вот на практике комментарии часто вредят. Как и любой вид писательского творчества, написание комментариев требует мастерства. Это мастерство в значительной мере включает в себя понимание того, когда комментарии писать не нужно.