Дьявол в деталях: как нам удалось оптимизировать разработку при помощи комментариев к коду
23 октября 2020

Дьявол в деталях: как нам удалось оптимизировать разработку при помощи комментариев к коду

Главный принцип нашей работы - постоянное развитие. Мы верим, что годные результаты может показать только тот, кто непрерывно учится, ищет нестандартные пути решения проблем и тестирует новые технологии. И дело тут даже не в самом развитии, а в признании его “бесконечности”. Нет никакой финишной черты и условного идеала. Любой процесс совершенствуется и подстраивается под постоянно изменяющиеся условия и тренды. Этот принцип мы применяем везде: и в управлении, и в продажах, и, конечно же, в разработке.

Главные ошибки оптимизации процесса разработки

Как показывает опыт наших коллег и нашей собственной команды, чаще всего мы наступаем на такие грабли:

  • 1. Революция на революции. Когда мы призываем к постоянному развитию, мы не говорим, что нужно разом перестраивать систему. Любые изменения стоит внедрять постепенно и смотреть, как они заходят и какие результаты показывают.
  • 2. Типовые решения. Вы читаете про очередную модель разработки, смотрите на кейсы, и думаете: “Вот оно! Теперь точно все взлетит!”. Только вот то, что идеально подошло одним, может оказаться совершенно нежизнеспособно для других.
  • 3. Чересчур общий взгляд. Мы смотрим на разработку как на большой общий процесс и пытаемся подогнать его под модель: инкрементную, каскадную, итеративную, спиральную, agile, RAD и т.д. Очередная модель не срабатывает, вы начинаете искать причины, и в итоге находите их на каком-то настолько локальном уровне, что “и смех, и грех”.

Наш локальный пример - комментарии к коду

Наш любимый пример про локальные проблемы - комментарии к коду, этика которых позволила нам сократить время на разработку на 10%. Десять процентов, Карл! На комментариях.

Обнаружилась проблема довольно неожиданно - при анализе работы разработчиков с высокими показателями. Тут надо оговориться, что это один из принципов нашего мониторинга - мы не “упарываемся” в поиск только ошибок, как делают многие, но еще и анализируем успехи. Так вот, рассматривая работу разработчиков, которые легко включались в процесс, работая с чужим кодом, мы обнаружили, что у каждого из них было подспорье в виде грамотных комментариев к коду.

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

  • 1. Всегда оставляют комментарии к коду, поясняют каждое действие, даже если оно очевидно из самого кода.
  • 2. Вообще не оставляют комментарии, утверждая, что хороший код описывает себя сам.
  • 3. Оставляют комментарии только там, где чувствуют потребность в пояснении.

Давайте посмотрим, как эти три подхода работают на практике.

1. Комментарии есть везде

Чтобы добавить наглядности, давайте возьмем пример.

					function int GetSumOf(value1: number, value2: number){
										return value1 + value2;
									}
			

Как раз тот случай, когда код описывает себя сам. Всё прозрачно: “Получить сумму из двух чисел”.

Стоит ли писать к этой функции комментарий? Ответа может быть два:

  • 1. Нет, если проект разрабатывается внутри компании. Лучше сэкономить время и потратить его на более полезные действия.
  • 2. Да, если идет разработка функционала/фреймворка для общедоступного использования. В таком случае комментарии даже к простейшим функциям - хороший тон.

Главное преимущество такого подхода - следующий разработчик (или тот же, но спустя продолжительное время) никогда не запутается в коде. Все пояснения на месте, вопросов - минимум.

А есть ли подводные камни? Непременно, даже два.

Во-первых, проблема подхода “комментируем все” кроется в том, что комментарии могут терять всю ценность при небрежном редактировании (код переписали, а комменты так и остались). Когда идёт рефакторинг, мало кто заботится о комментарии, написанном для этого кода, и в конце концов все пояснения становятся мусором.

Во-вторых, некоторые комментарии оказываются бессмысленными, если они пишутся ради того, чтобы были, например;”ID поля”. Чем этот комментарий может помочь? Мы и так видим, что там ID какого-то поля, но что это за поле, зачем оно? Такие комментарии обычно возникают, когда разработчику ставят задачу писать комментарии везде, но он это делает “на отвяжись”.

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

2. Комментариев нет вообще

Приверженцы такого подхода обычно приводят два аргумента в его пользу:

  • 1. Хороший код должен описывать сам себя, и каждая функция должна легко считываться из его содержимого.
  • 2. Отсутствие комментариев экономит время и на написание, и на редактирование кода.

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

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

3. Комментарии по необходимости

Нетрудно догадаться, что третий подход - самый разумный. Но у него есть свои подводные камни:

  • 1. У разных разработчиков разное понимание “очевидного”. Тот момент, который не требуется пояснять одному, может быть непонятен другому. Лечится эта проблема просто: разработчик заканчивает свой код, оставляя на ходу комментарии в тех местах, которые ему кажутся неочевидными, а потом показывает код непредвзятому коллеге. Пробежать глазами кусок кода - задача, которая требует минимум времени, но приносит максимум пользы.
  • 2. Комментарии тоже нужно вычитывать, потому что иногда они могут не отвечать на вопросы, а плодить новые.

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

Примеры непонятных комментариев к коду:

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

  • 1. Что за реквизиты ?
  • 2. Что за URL ?
  • 3. Что за токен ?
  • 4. Что за ключ ?
  • 1. Что за фильтр файлового хранилища ?
  • 2. Какой путь имеется в виду?
Примеры хороших комментариев:

Сразу понятно, что это - модель о результате активации сервиса, которая содержит признак того, что сервис активирован, есть демо период для этого сервиса и его название.

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

Нормально делай - нормально будет

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

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

Мы наглядно показали, какие комментарии вызывают вопросы, а какие - на них отвечают. И это отличный опыт, потому что по дефолту разработчики редко взаимодействуют друг с другом и не задумываются, что с их кодом потом будут работать другие ребята.

Вот так мы получили ценный опыт, подтверждение поговорки “дьявол кроется в деталях” и сумели оптимизировать рабочий процесс. Чего и вам желаем ;)

Комментарии для сайта Cackle

Сервисы 1С для работы с маркетплейсами