Чи є сенс включати "журнал змін" у кожен файл коду, коли ви використовуєте контроль версій?

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

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

і:

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

Причина цього, як мені було пояснено, полягає в тому, що просівати наші журнали VCS потрібно занадто багато часу, намагаючись знайти, хто що змінив і чому, маючи це в самому файлі коду, вгорі або біля відповідного зміни, дозволяє легко побачити, хто змінив, що і коли. Хоча я бачу сенс у цьому, це здається зайвим і просто таким присмаком "Е-е, ми насправді не розуміємо, як правильно використовувати наш VCS, тому ми не будемо взагалі турбуватися з цими речами".

Що ти думаєш? Чи використовуєте ви як коментарі, так і журнал? Просто журнал? Чи вважаєте ви, що простіше кодувати, коли ви бачите вище блоку коду, що Джон Сміт тиждень тому змінив метод перевірки на XYZ, замість того, щоб шукати журнали та порівнювати файли коду в інструменті Diff?

EDIT: Використання SVN, але в основному лише як сховище. Ні гілок, ні злиття, нічого, крім журналу + зберігання.

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

Тож не повинно вас дивувати, що я б також видалив ці журнали змін із тієї самої причини.

Проблема коментованого коду та коментарів, які читаються як книги, полягає в тому, що ви насправді не знаєте, наскільки це актуально, і це дає помилкове розуміння того, що насправді робить код.

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

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

Але щоб ви не думали, що я скажу, що коментарі слід видаляти на жарт, це щоденне подання WTF (з кодової бази, над якою я працював) чудово ілюструє мою думку:

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

О ... Історії, які я міг би розповісти вам про цю кодову базу, і я хотів би, за винятком того, що вона все ще використовується однією з найбільших урядових організацій навколо.

Ці "журнали змін", вбудовані в код, особливо непристойні. Вони просто виявляються ще однією різницею, коли ви відрізняєтесь редакціями, і тією, про яку ви насправді не цікавите. Повірте свій VCS - у більшості є функція "вини", яка дуже швидко покаже, хто що змінив.

Звичайно, справді жахлива річ полягала в тій особливості "старих" VCS, де ви могли мати фактичний журнал VCS, вбудований у вихідні файли. Зробити злиття майже неможливо.

У мене є один файл ChangeLog для кожного проекту, який автоматично заповнюється певними повідомленнями фіксації.

У нас немає вбудованих коментарів ChangeLog. Якби ми це зробили, я видалив би їх і поговорив з особою, яка їх додала. Я думаю, що вони свідчать про нерозуміння інструментів, які ви використовуєте, зокрема, vcs.

У нас є формат повідомлень про фіксацію, який полегшує збирання журналів. Ми також забороняємо марні чи неоднозначні повідомлення про вчинення.

Я особисто заперечую журнали змін у файлі вихідного коду. Мені просто здається, що це порушує принцип інженерії програмного забезпечення, оскільки будь-які зміни, які я вношу, повинні бути здійснені в декількох місцях. Багато разів інформація журналу змін є абсолютно марною і неважливою. На мою скромну думку, зміни програмного забезпечення повинні бути задокументовані, коли ви перевіряєте код.

Але що я знаю ...

Я думаю, що якщо є настій на впровадження практики зберігання журналу змін у вихідному коді, то журнал змін повинен бути обмежений змінами, які впливають на pulic API / інтерфейс класу. Якщо ви вносите зміни в класі, які не збираються порушувати жоден код, який його використовує, записування цих змін у журналі змін, на мою думку, просто захаращується. Однак я можу бачити, як іноді може бути зручно перевірити вгорі файл вихідного коду на предмет документації щодо будь-яких змін, які, можливо, зламали щось для кого-небудь іншого. Лише короткий підсумок того, як зміни можуть вплинути на API та чому вони були внесені.

З іншого боку, в моєму магазині в основному є речі C #, і ми завжди використовуємо вбудовані коментарі XML для документування нашого API, тому читання документації щодо змін у публічному API є більш-менш простим, як використання інтеліссенса.

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

Остання компанія, в якій я працював, мала програмне забезпечення, яке мала 17-річну історію, розробку та щорічні оновлення. Не всі міграції з однієї системи контролю версій на іншу зберігають коментарі чи примітки до реєстрації. Також всі розробники протягом цих років не дотримувались узгодженості з коментарями / замітками щодо реєстрації.

З коментарями до вихідного коду археологічна історія змін зберігалася як примітки, а не коментована. І так, вони все ще доставляють код VB6.

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

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

У моїй теперішній компанії нам потрібно подавати коментар при кожному заїзді. Не тільки це, але, як очікується, ми додамо кожний чек із квитком у Джирі. Якщо ви заглянете в Jira в майбутньому, ви можете побачити кожен файл, який був зареєстрований, і коли для цього питання, а також коментар, який залишився. Це досить зручно.

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

Це залишок часів, коли журнали VCS були заплутані, а системи VCS були важкі для обробки (я пам’ятаю ті дні, десь на початку 80-х).

Ваша підозра є цілком правильною, ці коментарі є скоріше перешкодою, ніж допомогою, і будь-який сучасний VCS дозволить вам знайти саме те, що ви шукаєте. Звичайно, вам (та вашим колегам) доведеться витратити бл. 30-60 хвилин, як навчитися керувати всіма цими функціями (що, я підозрюю, насправді є причиною, чому ці коментарі все ще є).

Я тримаю це (майже) з Джорджем. Коментарі в коді дійсно виправдані, лише якщо вони пояснюють щось, що не видно відразу в самому коді. І це трапляється рідко в хорошому коді. Якщо у вас є потреба у коментарях у вашому коді, це власний запах, і він кричить "рефактор мене!".

Ми все ще включаємо їх у джерело збережених процедур, оскільки саме так ми можемо точно сказати, яка версія є у клієнта. Решта програми розподіляється складеною, тому у нас є номери версій модулів, які посилаються на джерело, але SP-файли розподіляються як джерело для клієнтів для локальної компіляції в базі даних.

Наш застарілий код PowerBuilder все ще використовує їх, але я думаю, що це лише як фактор комфорту для певних зазирків. Це також збирається для розповсюдження, тому (IMO вони повинні) використовувати історію VCS friggin.

Якщо ви використовуєте SVN, це марно витрачає час і зовсім марно.

SVN виконує функцію вини. Це точно скаже вам, хто робив кожен рядок у заданому файлі та коли.

Коментарі коментарів до журналу винятково корисні в коді, коли вони допомагають наступному розробнику задавати кращі запитання щодо нових вимог. Наприклад, коли розробник бачить коментар, наприклад, що Фред зробив поле Foo необхідним 6 місяців тому, щоб задовольнити певну вимогу, він розробник знає, що їм потрібно задати питання, перш ніж реалізувати останній запит, щоб зробити Foo необов'язковим. Якщо ви маєте справу зі складними системами, різні зацікавлені сторони, ймовірно, мають різні пріоритети та різні бажання. Зауваження до журналу змін можуть бути дуже корисними для документування того, хто з цих вигідних заходів був здійснений, щоб уникнути проблем у майбутньому.

Тепер, якщо кожен розробник перевірив повну історію кожного рядка коду, перш ніж вносити будь-які зміни, ці коментарі в коді були б зайвими. Але це дуже нереально як з точки зору робочого процесу - більшість розробників просто змінить перевірку, не досліджуючи історію того, хто її додав і чому - і з точки зору технологій - система контролю версій буде складно відслідковувати "те саме "рядок коду, якщо він перемістився з одного рядка в інший або був перетворений на інший клас. Коментарі в коді набагато більше шансів побачити і, що ще важливіше, спонукати наступного розробника зазначити, що, здавалося б, проста зміна може бути не такою простою.

При цьому, змінити коментарі до журналу в коді повинні бути досить рідко. Я не виступаю за те, щоб коментарі до журналу змін додавалися щоразу, коли трішки коду буде відновлено, або коли виправлена ​​справжня помилка. Але якщо початкова вимога була "Foo необов'язково", і хтось приходить і змінює вимогу на "Foo потрібен для підтримки Bar нижче процесу", - це те, до чого я б настійно розглядав можливість додавання коментаря. Оскільки існує велика ймовірність того, що якийсь майбутній користувач / аналітик буде невідомий про подальний процес Bar і не знає про те, чому Foo був необхідний, і попросить зробити Foo знову необов'язковим і викликати головні болі в процесі Bar.

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

Я здивований, коли ніхто не згадував про це, але чи не первісна причина цього дотримання ліцензійних вимог? Тобто деякі ліцензії кажуть, що будь-які зміни, внесені до файлу, повинні бути помічені у самому файлі?

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