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

Хорошо ли названы переменные, методы и классы, которые вы создали? Позволяют ли они понять, что делают и для чего? Не будьте избыточны (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;

}

Коллаборация

Вам часто придется работать над кодом, написанным не вами. Работа с чужим кодом – дело непростое: вы должны понять, как он работает, привыкнуть к стилю автора. Код может быть написан неидеально, запутанно или неряшливо. В любом случае вы должны уважать чужой труд.

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

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

Полагайтесь на тесты кода, который вы исправляете, либо напишите их, если позволяют задача и время: вы должны быть уверены, что не допустите новых ошибок. В данном случае будет лучше написать тесты на существующий код, после чего приступить к его исправлению. Таким образом, закончив, вы сможете проверить код уже написанными тестами и убедиться в том, что логика работы не нарушена.

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

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

Тезисы

■ Уважайте чужой код.

■ Корректная работа кода всегда важнее его внешнего вида.

■ Если есть возможность, пообщайтесь с автором исправляемого кода.

■ Напишите тесты до начала исправлений и проверьте уже исправленный код.

■ Избегайте конфликтов с коллегами.

Задание

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

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

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

Отладка

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

В зависимости от языка программирования проекта вам будут доступны разные способы отладки. Некоторые языки программирования предоставляют очень богатые возможности для отладки, другие, наоборот, не имеют их совсем. Но не стоит отчаиваться: даже работая с языками, чьи средства отладки минимальны, вы всегда сможете воспользоваться встроенными средствами диагностики, пусть даже это будет простой вывод на экран.

Самый простой