Каков наилучший подход для комментариев встроенного кода?


13

Мы проводим рефакторинг 20-летней устаревшей кодовой базы, и я обсуждаю с моим коллегой формат комментариев в коде (plsql, java).

Для комментариев нет формата по умолчанию, но в большинстве случаев люди делают что-то подобное в комментарии:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

Предлагаемый формат для будущих и прошлых комментариев, которые я хочу, это:

// {yyyy-mm-dd}, unique_author_company_id, comment

Мой коллега говорит, что нам нужен только комментарий, и мы должны переформатировать все прошлые и будущие комментарии в этот формат:

// comment

Мои аргументы:

  • Я говорю по причинам обслуживания, важно знать, когда и кто сделал изменение (даже эта информация находится в SCM).
  • Кодекс жив, и по этой причине имеет историю.
  • Потому что без дат изменения невозможно узнать, когда было внесено изменение, без открытия инструмента SCM и поиска в длинной истории объекта.
  • поскольку автор очень важен, смена авторов более вероятна, чем смена автора
  • Причины гибкости, нет необходимости открывать и перемещаться через инструмент SCM
  • люди будут бояться изменить то, что кто-то сделал 15 лет назад, чем то, что было недавно создано или изменено.
  • и т.п.

Аргументы моего коллеги:

  • История в СКМ
  • Разработчики не должны знать историю кода непосредственно в коде
  • Пакеты получают 15 тыс. Строк, а неструктурированные комментарии затрудняют понимание этих пакетов

Как вы думаете, это лучший подход? Или у вас есть лучший подход для решения этой проблемы?


8
Вы действительно должны изучить функцию обвинения / аннотации / замедленной съемки вашего SCM. Для каждой строки в файле показано, в какой ревизии эта строка была изменена в последний раз. Нет необходимости искать в длинной истории.
Карл Билефельдт

FWIW, где я работаю, мы используем третий формат (базовый комментарий) для обычных описательных комментариев, но обязаны указать автора, дату и время, а также пояснения, когда происходят изменения в коде. Однако, когда это было реализовано, было несогласие по причинам, указанным ниже.
Роберт Харви

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

3
Я согласен на 100% с вашим коллегой
Вим

Ответы:


32

Общие комментарии

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

Таким же образом date / authorInfo ничего не дает вам с точки зрения того, почему код был сделан таким образом; точно так же, как то, как оно может выродиться со временем, потому что никакие инструменты не применяются. Также та же информация уже хранится в системе контроля версий (поэтому вы дублируете усилия (но менее надежным способом)).

Проходя через аргументы:

Я говорю по причинам обслуживания, важно знать, когда и кто сделал изменение (даже эта информация находится в SCM).

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

В коде есть жизнь, по этой причине была история.

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

Потому что без даты изменения невозможно узнать, когда было внесено изменение, без открытия инструмента SCM и поиска в длинной истории объекта.

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

поскольку автор очень важен, смена автораx более вероятна, чем смена автора

Все авторы (кроме вас) одинаково заслуживают доверия.

Причины гибкости, нет необходимости открывать навигацию по инструменту SCM

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

люди будут бояться изменить то, что кто-то сделал 15 лет назад, чем то, что было сделано за последнее время ...

Если код длится 15 лет, то он, скорее всего, будет более надежным, чем код, который длится всего 6 месяцев без проверки. Стабильный код имеет тенденцию оставаться стабильным, глючный код со временем становится все более сложным (так как причина глючности в том, что проблема не так проста, как кажется на первый взгляд).

Еще больше причин использовать контроль источников для получения информации.

История в СКМ

Да. Лучшая причина еще.

Разработчики не должны знать историю кода непосредственно в коде

Если мне действительно нужна эта информация, я буду искать ее в системе контроля версий.
В противном случае это не актуально.

Пакеты получают 15 тыс. Строк и неструктурированные комментарии, эти пакеты сложнее понять

Комментарии должны быть описанием того, почему вы что-то делаете.
Комментарии НЕ должны описывать, как работает код (если алгоритм не очевиден).


ТКС за ваш ответ, достаточно аргументов, чтобы изменить мою точку зрения :)
Диего Альварес

4
+1. Только одно добавление: намного сложнее обмануть систему контроля версий, чем текстовый редактор (или опечатка, или ошибка, или что-то еще).
tdammers

если мы говорим, что только восемь месяцев назад мы начали использовать инструменты SCM для plsql, а коду уже 20 лет, что вы думаете, если мы удалим автора и дату из исторических комментариев изменений, которых нет в SCM? это имеет какой-то смысл? или в это время нет никакого смысла знать, кто и когда внес изменения 15-20 лет назад? TKS для вас время и ответ.
Диего Альварес

6

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

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

В конце концов, вы нанимаете программистов, а не рассказчиков историй ;-)

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.