■ Спрашивайте, спрашивайте и спрашивайте.
■ Не бойтесь допускать ошибки; разработчиков, которые приходят на новый проект и моментально пишут идеально подходящий код, не существует.
Задание
Просмотрите коммиты вашего проекта и найдите те, которые реализуют что-то новое. Попытайтесь понять, чем руководствовался автор кода, и оценить, насколько его код соответствует принципам проекта, общему стилю, подходам к решению задачи.
История из жизни
На одном из проектов с очень амбициозным и своенравным главным разработчиком мне пришлось 20 раз переписывать одну из своих первых задач. Сложность была в том, что мой код должен был выглядеть как его код, а писали мы очень по-разному. Задачу я все же завершил, но сделал для себя выводы о том, что нельзя заставить людей писать так, как хочется тебе, а не им. В дальнейшем этот пример очень помогал мне находить общий язык с новыми разработчиками на проекте. Каждый раз, когда мне хотелось, чтобы их код был похож на мой, я вспоминал эту историю и просто находил компромисс.
Код как документация
Многие из вас знают, что документирование кода – отличная и даже обязательная практика. Кто-то из вас слышал, что лучшая документация – это сам код, написанный так, чтобы он не нуждался в дополнительном описании. Оба утверждения верны, однако в реальной жизни вы чаще будете работать с кодом, документация и качество которого оставляют желать лучшего (не пугайтесь, вы же разработчик, а значит, сможете это исправить).
Документация – это очень широкий термин, охватывающий многие стороны проекта. Можно говорить о комментариях в самом коде, а также об обязательной документации в коде библиотек, если вы их создаете и предполагаете, что их будут использовать другие разработчики.
Подходы к созданию документации тоже бывают разными: это могут быть комментарии самих разработчиков или труд нескольких специалистов вашей команды, основная работа которых – составление документации проекта. Документация может писаться вручную, собираться автоматически из кода проекта или генерироваться из схем 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.
Тезисы
■ Пишите код как документацию.
■ Документируйте емким текстом.
■ Иногда код не может быть простым – документируйте!