От джуна до сеньора: Как стать востребованным разработчиком

Код как документация

Многие из вас знают, что документирование кода – отличная и даже обязательная практика. Кто-то из вас слышал, что лучшая документация – это сам код, написанный так, чтобы он не нуждался в дополнительном описании. Оба утверждения верны, однако в реальной жизни вы чаще будете работать с кодом, документация и качество которого оставляют желать лучшего (не пугайтесь, вы же разработчик, а значит, сможете это исправить).

Документация – это очень широкий термин, охватывающий многие стороны проекта. Можно говорить о комментариях в самом коде, а также об обязательной документации в коде библиотек, если вы их создаете и предполагаете, что их будут использовать другие разработчики.

Подходы к созданию документации тоже бывают разными: это могут быть комментарии самих разработчиков или труд нескольких специалистов вашей команды, основная работа которых – составление документации проекта. Документация может писаться вручную, собираться автоматически из кода проекта или генерироваться из схем API. Сейчас мы будем говорить только о документировании кода как о наиболее частом случае.

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

Хорошо ли названы переменные, методы и классы, которые вы создали? Позволяют ли они понять, что делают и для чего? Не будьте избыточны (Java, спасибо, что зашел): если вы написали метод add, состоящий из одной строчки кода и суммирующий два числа, не стоит писать к нему документацию. С другой стороны, если вы написали метод, который вычисляет плотность населения на квадратный метр, используя для этого анализ сигналов с мобильных телефонов, – пожалуйста, документируйте это так, чтобы за это выдали премию (а еще вы основательно наплевали на наши права и свободы).

Старайтесь комментировать код по возможности компактно. Краткие и емкие комментарии не будут отвлекать разработчиков при беглом осмотре кода, тогда как избыточная информация станет помехой и усложнит рефакторинг.

Хороший проект – это вкусный коктейль из качественно написанного кода, который не требует документации, и емких комментариев в местах, где трудно разобраться с ходу. Не каждый код можно сделать простым, иногда вам ничего не остается, кроме как описать происходящее словами (и это абсолютно нормально).

Несколько смешных примеров комментариев (надеюсь, вы не встретите подобного в вашем проекте):

// Dear maintainer:

//

// Once you are done trying to 'optimize' this routine,

// and have realized what a terrible mistake that was,

// please increment the following counter as a warning

// to the next guy:

//

// total_hours_wasted_here = 42

// I am not sure if we need this, but too scared to delete.

// When I wrote this, only God and I understood what I was doing

// Now, God only knows

return 1; # returns 1

// somedev1–6/7/02 Adding temporary tracking of Login screen

// somedev2–5/22/07 Temporary my ass

// I am not responsible of this code.

// They made me write it, against my will.

Тезисы

■ Пишите код как документацию.

■ Документируйте емким текстом.

■ Иногда код не может быть простым – документируйте!

Задание

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

История из жизни

На одном из проектов, где я работал, было принято решение комментировать весь написанный код, независимо от того, насколько он прост и понятен. Разработчики любят предсказуемость и простоту, однако оказавшись в ситуации, где формализм существует ради формализма, вы в итоге получаете что-то такое:

// check if operation was a success

if (isSuccess) {

// return success marker

return MARKER_SUCCESS;

}