Комментарии для проигравших

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

ехать по этой дороге. Иногда следующим несчастным водителем будет ты через несколько лет!

Комментарии не обязательно увеличивают скорость разработки

В 1985 году я учился в университете (да, я старый парень), и один из моих профессоров представил документ (который я не смог найти) исследования, проведенного в 1970-х годах. В ходе исследования была взята программа, введены дефекты, а затем несколько команд попросили найти как можно больше дефектов. Интересной частью исследования было то, что 50% команд полностью удалили комментарии из исходного кода. В результате команды без комментариев не только обнаружили больше дефектов, но и нашли их за меньшее время .

Так что, к сожалению, комментарии могут служить оружием массового отвлечения …

Плохие комментарии

Плохой комментарий — это тот, который тратит впустую ваше время и не помогает вам ускорить разработку. Давайте рассмотрим категории действительно плохих комментариев:

• Слишком много комментариев
• Чрезмерные исторические комментарии
• Эмоциональные и юмористические комментарии

Слишком много комментариев — явный случай, когда меньше — больше. Есть программы с таким количеством комментариев, что это затеняет код. Некоторые из нас работали над программами, в которых было так много комментариев, что вы едва могли найти код!

Комментарии к истории могут иметь некоторый смысл, но опять же, разве не для этого нужен комментарий управления версиями? Комментарии к истории сомнительны, когда вам приходится несколько раз пролистывать страницу, чтобы перейти к началу исходного кода. Во всяком случае, комментарии к истории должны быть перемещены в конец файла, чтобы Ctrl-End фактически переместил вас в конец истории изменений.

Мы все сталкиваемся с комментариями, которые не имеют отношения. Некоторые комментарии касаются исключительно эмоционального и интеллектуального состояния разработчика, некоторые о том, насколько они умны, а некоторые — просто попытки юмора (не бросайте свою повседневную работу!). Проверьте некоторые из этих драгоценных камней (больше может быть найдено здесь ):

Самодокументированный код вместо комментариев

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

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

Комментарии сошли с ума

Даже если все комментарии в программе хороши (то есть сокращают жизненный цикл разработки), они со временем могут дрейфовать . Скорость разработки программного обеспечения затрудняет обеспечение соответствия комментариев исходному коду. Комментарии, которые могут сместиться, становятся дорожными знаками, которые больше не относятся к водителям. Хорошие комментарии сходят с ума, когда разработчик настолько сосредоточен на выпуске релиза, что не перестает поддерживать комментарии. Комментарии становятся дикими, когда они не совпадают с исходным кодом; Вы должны прекратить их. Никакие животные (или комментарии) не пострадали при написании этого блога.

Код комментирования

Код комментируется во время выпуска программного обеспечения, поскольку мы экспериментируем с различными конструкциями или помогаем с отладкой. На самом деле неясно, почему код остается прокомментированным перед окончательной проверкой выпуска программного обеспечения.

За свою карьеру менеджера и тренера я спросил разработчиков, почему они комментируют свой код. Универсальный ответ, который я получаю, — «на всякий случай». На всякий случай что? В конце выпуска программного обеспечения вы уже установили, что не собираетесь использовать закомментированный код, так почему вы его таскаете? Люди держатся за комментированный код, как если бы это была карта « Get Out of Jail Free », это не так.

Реальность такова, что прокомментированный код может сильно отвлекать. Когда вы оставляете закомментированный код в своем исходном коде, вы оставляете наземную шахту для следующего разработчика, который проходит через нее. Когда давление устраняется, разработчики будут раскомментировать ранее прокомментированный код, чтобы увидеть, решит ли он проблему. Ничто не заменит понимание кода, над которым вы работаете, — вам может повезти, если вы восстановите закомментированный код; по всей вероятности, он взорвется вам в лицо.

Решения

Если ваши разработчики не уделяют (или не дают) достаточно времени, чтобы добавить хорошие комментарии, им не следует писать НИКАКИЕ комментарии. Вы получите больше производительности, потому что они не будут тратить время на плохие комментарии, которые замедляют всех остальных. Время, потраченное на написание самодокументируемого кода, поможет вам и вашим преемникам сократить жизненные циклы разработки. Абсолютно неверно полагать, что у вас нет времени на написание самодокументируемого кода. Если вы собираетесь взять на себя риски написания комментариев, то они должны быть рецензированы, чтобы убедиться, что другие разработчики понимают код. Если рецензент (ы) кода не понимает все комментарии, код не должен проходить проверку.

Если у вас нет процесса проверки кода, тогда вы только комментируете код для себя. Ключевым принципом при написании комментариев является Non Nobis Solum (не для нас самих). Когда вы сталкиваетесь с комментарием, который отправляет вас в погоню за диким гусем — исправьте его или удалите. Если вы новичок в команде и понимаете, что комментарии тратят ваше время — избавьтесь от них; Ваша скорость разработки будет расти.

Не заблуждайтесь, я самый большой «неудачник» из всех. Я считаю, что я сделал каждую ошибку в книге хотя бы один раз 🙂