От джуна до сеньора

// 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;

}

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

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

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

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

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

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