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

Мы проводим рефакторинг 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 тыс. Строк, а неструктурированные комментарии затрудняют понимание этих пакетов

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

История в СКМ

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

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

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

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

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

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

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

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