Учтя все сказанное, задайте себе вопрос, насколько понятно ваш код может рассказать вам или другому программисту, что он делает.
Вы можете сказать: «О, так в моих комментариях есть все, что нужно знать». Но учтите, что комментарии — это не работающий код. Они могут вводить в заблуждение так же, как любая другая документация. Традиционно считалось, что комментарии — безусловно хорошая практика, поэтому некоторые программисты без всяких раздумий пишут обширные комментарии, даже повторяя и разъясняя в них факты, и без того очевидные из собственно кода. Это плохой способ сделать код понятным.
Если ваш код нуждается в комментариях, попробуйте провести рефакторинг так, чтобы они стали не нужны. Пространные комментарии загромождают экран, а ваша IDE может автоматически их скрывать. Если нужно пояснить изменение, сделайте это не в коде, а с помощью сообщения при сохранении кода в систему управления версиями.
Что можно сделать, чтобы ваш код действительно говорил правду и как можно яснее? Старайтесь выбирать хорошие имена. Структурируйте код с учетом сильносвязанной (cohesive) функциональности, что также облегчает выбор имен. Уменьшите (decouple) связанность кода, чтобы достичь ортогональности. Напишите автоматизированные тесты, раскрывающие запланированное поведение, и проверьте интерфейсы. Безжалостно переделывайте код, если найдете способ написать проще и лучше. Старайтесь, чтобы ваш код был как можно проще для чтения и понимания.
Относитесь к своему коду как к любому другому творческому тексту — стихотворению, эссе, записи в открытом блоге или важному электронному письму. Тщательно формулируйте то, что хотите выразить, чтобы код делал то, для чего предназначен, и как можно проще сообщал, что он делает, — так, чтобы ваши намерения были ясны, когда их нельзя уже будет узнать у вас самого.
Помните, что полезным кодом пользуются гораздо дольше, чем предполагают его авторы. Те, кто будут сопровождать ваш код, останутся вам благодарны. А если вы сами занимаетесь сопровождением, и код, с которым вы работаете, не спешит раскрыть свои тайны, как можно раньше начните применять вышеупомянутые принципы. Придайте здравый смысл коду, чтобы сохранить собственный здравый рассудок.
Возьмите сборку (и ее рефакторинг) на себя
Стив Берчук
Не столь уж редки случаи, когда команды, в целом дисциплинированно соблюдающие хорошие практики написания кода, пренебрежительно относятся к сценариям сборки. Их считают либо малозначительными, либо настолько сложными, что обслуживать их может только секта специалистов по выпуску продукта (release engineers). Если сценарии сборки сложны в сопровождении, содержат дублирование и ошибки, это приводит к проблемам того же масштаба, что и плохо спроектированный код.
Почему ответственные и грамотные разработчики считают сборку проекта некой второстепенной работой? Одно из объяснений — сценарии сборки часто пишут на ином языке, чем исходный код. Второе — сценарии сборки не являются «кодом». Такие объяснения противоречивы, ведь большинство разработчиков с удовольствием изучает новые языки, а именно в результате сборки появляются исполняемые модули, которые разработчики и конечные пользователи будут тестировать и запускать. Код бесполезен, если из него не собирается исполняемый модуль, а ведь именно сборка определяет компонентную архитектуру приложения. Сборка — важная часть процесса разработки, и решения в области сборки способны упрощать и сам код, и процесс его написания.
Если в сценариях сборки используются неверные идиомы, такие сценарии тяжело сопровождать и, что хуже, тяжело улучшать. Стоит потратить некоторое время, чтобы разобраться, как правильно вносить изменения. Если приложение собирается с неверными версиями зависимых библиотек или во время сборки заданы неверные параметры конфигурации, это может вызвать ошибки в самом приложении.