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

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

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

«Почему, черт возьми, я сделал это таким образом!?»

Мы все сталкиваемся с этой ситуацией в какой-то момент нашей карьеры. Это может быть небольшая задача, о которой мы не слишком много думали; это могло быть из-за недостатка знаний, что мы каким-то образом решили использовать более неэффективный подход; возможно также, что мы просто забыли, почему мы так поступали. Что бы это ни было, конечным результатом является то, что мы написали какой-то код, который не знаем, как расшифровать.

Это время, когда мы задаемся вопросом, почему мы не оставили некоторые комментарии, хотя бы строчку или две.

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

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

Оставляя некоторые комментарии в коде, вы в основном говорите другим, а также себе в будущем, о чем вы думаете в данный момент: почему вы выбрали этот подход? Какая польза от такого поведения? Есть ли какое-либо ограничение, которое приводит к необходимости делать объезд?

Это то, что интересует людей. Это помогает им работать над своей задачей быстрее, потому что они узнают, как вы думаете, как реализована функция. В будущем вы также сможете быстро продолжить с того места, на котором остановилось ваше прежнее «я», и улучшить его.

Комментарии связывают людей, а комментарии связывают время.

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

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

Итак, что мы пишем, а что не пишем?

Вот несколько советов и рекомендаций, которым вы можете следовать:

  1. Напишите строку документации или резюме для описания метода, если он длинный и/или сложный. Кратко о том, что он ожидает, что возвращает и что делает.
  2. Если код написан не прямолинейно из-за ограничений (скажем, у вас не так много памяти, поэтому вам приходится делать что-то кусками), напишите несколько комментариев об ограничении и способе его решения.
  3. Если есть какой-то сложный расчет, напишите подробности о том, что происходит на каждом шаге, и, возможно, приведите несколько примеров.
  4. Если вы добавляете некоторые строки в существующую функциональность, которые изменяют бизнес-логику, добавьте строку с указанием номера тикета JIRA (или того, что вы используете) со ссылкой на тикет. Добавьте однострочное описание того, что он делает. Это избавляет других от необходимости искать историю ваших билетов.
  5. Если вам НЕОБХОДИМО соединить два метода вместе, когда изменение одной конфигурации в одном методе приводит к тому, что другой не работает, укажите это в комментарии и убедитесь, что тот, кто работает с этим методом, также проверяет другой метод на предмет возможных изменений.
  6. Эмпирическое правило комментирования, как сказал мой старый коллега, заключается в том, что комментарии заставляют людей восклицать: «Ага! Так вот почему это было сделано таким образом!»

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

Работы не много, но эффект невероятный.