Обслуговування коду: Щоб додати коментарі до коду чи просто залишити його на контролі версій?

Нас попросили додати коментарі із початковими тегами, кінцевими тегами, описом, рішенням тощо для кожної зміни, яку ми вносимо до коду, як частини виправлення помилки / впровадження CR.

Моє занепокоєння полягає в тому, чи це забезпечує якусь додаткову вартість? Як це є, у нас є всі деталі в історії управління версіями, які допоможуть нам відстежувати кожну зміну?

Але мої ведучі наполягають на тому, щоб коментарі були "гарною" практикою програмування. Одним з їх аргументів є те, що, коли необхідно змінити / змінити КР, було б громіздко, якщо коментарів немає.

Враховуючи, що зміни будуть значною мірою між кодом, чи дійсно допоможе додати коментарі до кожної зміни, яку ми внесли? Чи не слід залишати це на контролі версій?

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

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

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

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

Так замість

// fixed bug XXXXX on 10/9/2012

у вас може бути коментар, який говорить

// doing X, because otherwise Y will break.

або

// doing X, because doing Y is 10 times slower.

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

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

Але не пропускайте коментарів повністю: Хороші коментарі (не по-рабськи документуючи кожен старт / стоп / опис / рішення кожного виправлення та CR) покращують читабельність коду. Наприклад, для хитрого чи незрозумілого біта коду, який ви додаєте, щоб виправити помилку, коментар форми, який // fix ISSUE#413повідомляє людям, де можна знайти більше інформації у вашому трекері випусків, - прекрасна ідея.

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

Коментарі у VCS - про те, як змінився код. Їх слід читати як розповідь про розвиток.

Тепер кожна зміна повинна включати коментарі? у більшості випадків так. Єдиний виняток, який я собі уявляю, - коли очікувана поведінка вже була задокументована, але це не те, що у вас було, через помилку. Його виправлення робить наявні коментарі більш точними, тому їх не потрібно змінювати. Сама помилка повинна бути задокументована в історії квитків та коментарі, але лише в коді, якщо код виглядає дивним. У такому випадку // make sure <bad thing> doesn't happenмає бути достатньо.

Я дуже ціную один із типів коментарів:

// Це реалізовано для Правила 5 бізнесу 2 пропозиції

або що б там не було, ви використовуєте для збирання своїх вимог.

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

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

Ваші висновки мають рацію, коли кажуть, що коментарі є хорошою практикою програмування, проте є винятки. Додавання коментаря до кожної внесеної вами зміни - одна з них. І ви праві, сказавши, що це має належати до системи контролю версій. Якщо вам доведеться тримати ці коментарі в одному місці, то VCS - це шлях. Коментарі у вихідному коді, як правило, старіють і залишаються незмінними. Без коментарів набагато краще, ніж погані коментарі. Те, що ви не хочете, - це коментарі в обох місцях (у коді та VCS), які не синхронізовані. Мета полягає в тому, щоб уникнути НУМИ, маючи єдине джерело істини для змін у коді.

Окрім сказаного іншими, подумайте, що станеться, якщо зміна має наслідки пульсації у всій системі. Скажімо, ви рефакторируєте частину основного інтерфейсу в процесі впровадження запиту на зміну - така зміна може легко торкнутися великого відсотка файлів вихідного коду в будь-якій нетривіальній частині програмного забезпечення, що означає тривіальні зміни (клас або зміни назви методу). Чи маєте ви проходити кожен файл, який торкнувся такої операції, щоб вручну анотувати його такими коментарями, а не покладатися на те, що VCS робить це все автоматично? В одному випадку ви переглядаєте трохи більше п'яти хвилин роботи з будь-яким пристойним інструментом рефакторингу з подальшим перекомпіляцією, щоб переконатися, що нічого не порушило складання, тоді як інший може легко розмістити повітря на робочий день. Для якої конкретної вигоди?

Також врахуйте, що відбувається, коли ви переміщуєте частини коду навколо. Один із розробників баз даних, з яким я працюю, знаходиться в таборі, в основному "кожен рядок SQL повинен бути помічений з редакцією, в якій він був змінений, і ми збираємось робити окремі історії ревізій для кожного файлу, оскільки тоді це легше побачити хто змінив, що коли і чому ". Це працює якось добре, коли зміни єпро порядок зміни одиночних рядків. Це працює не так добре, коли, як і я нещодавно, щоб виправити серйозну проблему з продуктивністю, ви розбиваєте частини більшого запиту, вводячи тимчасові таблиці, а потім змінюєте впорядкування деяких запитів, щоб краще відповідати новому потоку коду. Зрозуміло, що розбіжність проти попередньої версії значною мірою втрачала сенс, оскільки в ній було сказано, що приблизно дві третини файлу змінилися, але коментар до реєстрації також був чимось на кшталт "основної реорганізації для вирішення проблем з продуктивністю". На той час, коли ви переглядали вручну обидві версії, було досить зрозуміло, що великі деталі насправді були однаковими, лише рухалися. (І потрібна збережена процедура займала від регулярного зайняття більше півхвилини до декількох секунд. До того часу,

За дуже невеликими винятками, відстеження змін та посилання на проблеми є роботою VCS, IMNSHO.

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

Однак якщо є не очевидна зміна, яка змінює логіку - особливо істотно змінює логіку, зроблену кимось іншим, неочевидним способом - може бути дуже вигідно додати щось на кшталт "ця зміна полягає в тому, щоб зробити це і що через помилку № 42742 ". Таким чином, коли хтось дивиться на код і замислюється "чому це тут? Це виглядає дивно", він має певні вказівки прямо напроти нього, і йому не потрібно проводити розслідування через VCS. Це також запобігає ситуаціям, коли люди порушують зміни інших, оскільки вони знайомі зі старим станом коду, але не помічають, що він змінився з тих пір.

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

Будь-яка інформація відстеження, яку можна витягнути з контролю версій, не повинна дублюватися в тілі коду. Це стосується дурних ідей, таких як ключові слова RCS-каси, як $Log$і їх подібні.

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

Деякі старі файли в ядрі Linux мають великі блоки коментування історії. Вони датуються тим часом, коли не було системи контролю версій, а лише тарілки та патчі.

Коментарі в коді повинні бути мінімальними та точними. Додавання інформації про дефекти / зміни не є цінною. Для цього слід використовувати контроль версій. Деякий час контроль версій забезпечує дещо кращий спосіб зміни. Ми використовуємо ClearCase UCM; Діяльність UCM створюється на основі номерів дефектів, області зміни тощо (наприклад, дефект29844_change_sql_to_handle_null).

Детальні коментарі бажані в коментарях до реєстрації.

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

Прамагічний програміст і CleanCode ведуть до наступних рекомендацій

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