Только код расскажет всю правду

(В оригинале - Only the Code Tells the Truth)

Поведение программы полностью определяется ее исполняемым кодом. Если у вас есть только исполняемый файл, разобраться в коде будет непросто. Однако исходный код должен быть доступен, если программа ваша, или же если вы имеете дело с open source или с купленной коммерческой разработкой, или же код написан на интерпретируемом языке. Взгляда на исходный код должно быть достаточно для понимания того, что делает программа. Более того, только исходный код даст вам все ответы. Даже наиболее детально проработанные исходные требования не сообщат вам всего, они содержат только высокоуровневые намерения. Дизайн содержит больше деталей, но и он все равно еще не содержит всех деталей реализации. К тому же эти документы могут не полностью соответствовать реализации. Или вообще могут не быть написаны. И исходный код – последнее, что у вас остается.

А теперь спросите себя, насколько ясно ваш код сообщает вам или кому-нибудь еще о том, что именно он делает?

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

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

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

Автор оригинала - Peter Sommerlad