Який найкращий підхід для вбудованих коментарів до коду?

Ми робимо деякий рефакторинг на застарілу базу даних коду, яка триває 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
• люди бояться більше змінити те, що хтось робив 15 років тому, ніж те, що було створено нещодавно чи змінилося.
• тощо.

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

• Історія знаходиться в СКМ
• Розробники не повинні знати про історію коду безпосередньо в коді
• Пакети отримують довгі 15 тисяч рядків, а неструктуровані коментарі ускладнюють розуміння цих пакунків

Як ви вважаєте, що найкращий підхід? Або у вас є кращий підхід до вирішення цієї проблеми?

Загальні коментарі

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

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

Переглядаючи аргументи:

Я кажу з міркувань технічного обслуговування, важливо знати, коли і хто змінив (навіть ця інформація є в СКМ).

Чому? Жодне з цих речей не вважає мене важливим для підтримки коду. Якщо вам потрібно поговорити з автором, знайти цю інформацію порівняно з джерелом управління досить просто.

Код має життя, з цієї причини була історія.

Історія зберігається в джерелі управління.
Ви також довіряєте, що коментар написав ця людина. Howкоментарі, як правило, деградують з часом, тому такий вид історії стає недостовірним. З іншого боку, системи контролю джерел підтримуватимуть дуже точну історію, і ви можете точно бачити, коли коментарі додавалися / видалялися.

Оскільки без дати зміни неможливо дізнатися, коли зміни були введені без відкриття інструменту SCM та пошуку в довгій історії об’єктів.

Якщо ви довіритесь даним у коментарі.
Однією з проблем подібного роду є те, що коментарі стають невірними стосовно коду. Поверніться до правильного інструменту для роботи. Система управління джерелом зробить це правильно, не потребуючи втручання з боку користувача. Якщо ваша система управління джерелом болить, то, можливо, вам доведеться або навчитися використовувати її більш доцільно (оскільки ця функціональність зазвичай проста), або якщо вона не підтримує її, знайти кращу систему управління джерелом.

оскільки автор дуже важливий, зміна autorx є більш достовірною, ніж зміна автора

Всі автори (крім вас самих) однаково достовірні.

Причини спритності, не потрібно відкривати навігаційний інструмент SCM

Якщо ваш інструмент управління джерелом є таким обтяжливим, ви його неправильно використовуєте або (це швидше), ви використовуєте неправильний набір інструментів для доступу до системи управління джерелом.

люди бояться змінити щось, що хтось робив 15 років тому, ніж те, що було зроблено

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

Ще більше підстав використовувати джерело управління для отримання інформації.

Історія знаходиться в СКМ

Так. Найкраща причина поки.

Розробники не повинні знати про історію коду безпосередньо в коді

Якщо мені справді потрібна ця інформація, я шукаю її в контролі джерел.
Інакше це не актуально.

Пакети отримують 15 к. Рядків і неструктуровані коментарі, які цей пакет важче зрозуміти

Коментарі повинні бути описом того, чому ви все одно щось робите.
Коментарі НЕ повинні описувати, як працює код (якщо алгоритм не очевидний).

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

Якщо код занадто складний, щоб його зрозуміти без написання тонн коментарів, я б запропонував вкласти вашу енергію в рефакторинг, щоб зробити код читабельним / ремонтопридатним без тонн коментарів.

Зрештою, ви наймаєте програмістів, а не сюжетів ;-)