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

Правду скажет только код Петер Зоммерлад

В конечном счете семантика программы определяется работающим кодом. Если он есть у вас только в виде бинарного файла, его будет непросто прочесть! Однако исходный код, как правило, доступен, если это ваша собственная программа, типичная коммерческая разработка, проект с открытым исходным кодом или программа на динамически интерпретируемом языке. При чтении исходного кода смысл программы должен быть очевиден. Можно с уверенностью узнать, что делает программа, только глядя в исходный код. Даже самое точное описание технических требований не скажет всей правды: в нем содержится не детальное описание того, что фактически делает программа, а общие пожелания составителя требований. Документ с архитектурой может содержать описание планируемой архитектуры, но в нем не будут описаны нужные детали реализации. Эти документы могут устареть в сравнении с текущей реализацией… или просто потеряться. Быть может, их даже и не писали. Возможно, единственное, что осталось, — это исходный код.

Учтя все сказанное, задайте себе вопрос, насколько понятно ваш код может рассказать вам или другому программисту, что он делает.

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

Если ваш код нуждается в комментариях, попробуйте провести рефакторинг так, чтобы они стали не нужны. Пространные комментарии загромождают экран, а ваша IDE может автоматически их скрывать. Если нужно пояснить изменение, сделайте это не в коде, а с помощью сообщения при сохранении кода в систему управления версиями.

Что можно сделать, чтобы ваш код действительно говорил правду и как можно яснее? Старайтесь выбирать хорошие имена. Структурируйте код с учетом сильносвязанной (cohesive) функциональности, что также облегчает выбор имен. Уменьшите (decouple) связанность кода, чтобы достичь ортогональности. Напишите автоматизированные тесты, раскрывающие запланированное поведение, и проверьте интерфейсы. Безжалостно переделывайте код, если найдете способ написать проще и лучше. Старайтесь, чтобы ваш код был как можно проще для чтения и понимания.

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

Помните, что полезным кодом пользуются гораздо дольше, чем предполагают его авторы. Те, кто будут сопровождать ваш код, останутся вам благодарны. А если вы сами занимаетесь сопровождением, и код, с которым вы работаете, не спешит раскрыть свои тайны, как можно раньше начните применять вышеупомянутые принципы. Придайте здравый смысл коду, чтобы сохранить собственный здравый рассудок.