Код как документация
Одной из характерных черт гибких методологий является то, что они возвышают программирование до центральной роли в процессе разработки программного обеспечения — гораздо большей, чем это обычно делает сообщество инженерии ПО. Одной из частей этого подхода является признание кода основным (а если не основным, то одним из самых важных) видом документации системы.
Сразу же хочу опровергнуть одно распространённое недопонимание. Такой принцип не означает, что код должен быть единственной формой документации. Хотя я часто слышал такое мнение относительно Extreme Programming (экстремального программирования), я никогда не слышал, чтобы лидеры этого движения сами так говорили. Обычно существует необходимость в дополнительной документации, которая будет дополнять и пояснять код.
Обоснование того, почему код считается главной формой документации, заключается в том, что только он достаточно подробный и точный, чтобы играть эту роль. Эту мысль очень убедительно выразил Джек Ривз в своём известном эссе «Что есть проектирование программного обеспечения?»
Этот принцип имеет важное следствие: программистам важно прикладывать усилия, чтобы сделать код понятным и читаемым. Утверждение, что код — это документация, не означает автоматически, что конкретная база кода является хорошей документацией. Как и любая другая документация, код может быть понятным или же бессвязным. Код сам по себе не более понятен, чем другие формы документации. (И другие виды документации тоже могут быть безнадёжно запутанными — я видел предостаточно бессмысленных диаграмм UML, чтобы подтвердить это.)
Безусловно, кажется, что большинство существующих баз кода — плохая документация. Но также ошибочно делать вывод, что объявление кода документацией исключает необходимость других форм документации, как и ошибочно полагать, что поскольку код часто оказывается плохой документацией, он обязательно всегда таков. Написать понятный код возможно, и я убеждён, что большинство баз кода можно сделать намного понятнее.
Я думаю, одна из причин, почему код так часто трудно читать, в том, что люди не воспринимают его всерьёз как документацию. Если нет желания сделать код понятным, то вряд ли он сам собой станет ясным. Поэтому первый шаг к созданию понятного кода — принять, что код есть документация, а затем приложить усилия, чтобы сделать его действительно понятным. Это зависит от того, чему учили большинство программистов в самом начале их пути. Мои преподаватели мало внимания уделяли ясности кода, они, казалось, не ценили её, и уж точно не обсуждали, как этого достичь. Всему нашему профессиональному сообществу нужно больше ценить понятность кода.
Следующий шаг — научиться писать понятный код. И здесь позвольте дать совет от популярного технического автора — ничто так не помогает, как рецензирование. Я бы никогда не опубликовал книгу, не дав нескольким людям прочитать её и не получив обратную связь. Точно так же ничего не заменит получение обратной связи от других людей относительно того, что в коде понятно, а что — нет. Поэтому используйте любую возможность, чтобы найти способы заставить других людей читать ваш код. Выясните, какие части им понятны, а какие вызывают путаницу. (Да, парное программирование — отличный способ сделать это.)
Если вам нужны более конкретные рекомендации — я предложу почитать хорошие книги о стиле программирования. Хорошее место для начала — книга "Code Complete". Естественно, я также порекомендую «Рефакторинг». Ведь во многом рефакторинг как раз направлен на улучшение читаемости кода. После «Рефакторинга» логично перейти к «Рефакторингу в сторону паттернов».
Вы всегда будете сталкиваться с тем, что люди по-разному понимают, как писать код. Помните, что база кода в первую очередь принадлежит всей команде (даже если в какой-то её части применяется индивидуальная ответственность). Профессиональный программист готов скорректировать свой личный стиль ради потребностей команды. Поэтому даже если вы любите использовать тернарные операторы, не стоит их использовать, если команда их плохо понимает. На своих личных проектах вы можете программировать в собственном стиле, но всё, что вы делаете в составе команды, должно соответствовать её потребностям.