Старший розробник нашого магазину наполягає на тому, що кожен раз, коли код буде змінений, відповідальний програміст повинен додати вбудований коментар із зазначенням того, що він зробив. Ці коментарі зазвичай виглядають так// YYYY-MM-DD <User ID> Added this IF block per bug 1234.

Ми використовуємо TFS для контролю ревізії, і мені здається, що подібні коментарі набагато доречніше як примітки до реєстрації, а не вбудований шум. TFS навіть дозволяє пов’язати реєстрацію з одним або кількома помилками. Деякі наші старі, часто модифіковані файли класів виглядають так, що вони мають коефіцієнт коментарів до LOC, що наближається до 1: 1. На мій погляд, ці коментарі ускладнюють читання коду та додають нульове значення.

Це стандартна (або принаймні поширена) практика в інших магазинах?

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

Однак я часто все-таки роблю щось подібне для конкретних типів правок.

Випадок 1 - Завдання

Якщо ви використовуєте такий IDE, як Eclipse, Netbeans, Visual Studio (або маєте якийсь спосіб пошуку тексту у вашій кодовій базі з будь-яким іншим), можливо, ваша команда використовує певні "теги коментарів" або "теги завдань". У цьому випадку це може бути корисно.

Я час від часу під час перегляду коду додаю щось подібне:

// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla

або:

// FIXME: [2010-12-09 haylem] marking this for review because blablabla

Для цього я використовую різні спеціальні теги завдань, які я бачу в Eclipse в області перегляду завдань, тому що мати щось у журналах фільмів - це добре, але недостатньо, коли у вас є керівник, який запитує вас на оглядовій нараді, чому помилка XY була повністю забута і прослизнув. Тож з нагальних питань чи справді сумнівних фрагментів коду, це служить додатковим нагадуванням (але зазвичай я залишаю коментар коротким і перевіряю журнали фіксації, оскільки ТОМУ чомусь нагадування тут, тому я не захаращую код також багато).

Справа 2 - Патчі сторонніх губ

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

// [PATCH_START:product_name]
//  ... real code here ...
// [PATCH_END:product_name]

Випадок 3 - Неочевидні виправлення

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

У продукті, над яким я працюю на даний момент, у нас іноді (напевно, це не звичайна річ) є коментар на кшталт:

// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ

Ми робимо це лише в тому випадку, коли помилка не очевидна і код читається ненормально. Це може бути, наприклад, вигадкою браузера, або неясними виправленнями CSS, які потрібно реалізувати лише тому, що в продукті є помилка документа. Таким чином, ми загалом пов'язуємо це з нашим внутрішнім сховищем випусків, яке потім міститиме докладні міркування про помилку та покажчики до документації про помилку зовнішнього продукту (скажімо, рекомендації щодо безпеки щодо відомого дефекту Internet Explorer 6 або щось схоже).

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

Це тільки в: Приклад із реального життя

У деяких випадках це краще, ніж нічого :)

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

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

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

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

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

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

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

На щастя, мої менеджери з тих пір більше знають, що можуть робити системи управління версіями (я мушу додати, що ми використовували SourceSafe в першому магазині). Тому я не додаю метадані версії до коду.

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

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

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

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

Вам потрібно зрозуміти, чому він не може на це покластися. Це старі звички? Поганий досвід роботи з системою SCM? Формат презентації, який не працює для нього? Можливо, він навіть не знає про такі інструменти, як "git blama" та часовий вигляд Perforce (що по суті це показує, хоча це може не показувати, яка проблема викликала зміни).

Не розуміючи його причини вимоги, ви не зможете переконати його.

Я працюю над продуктом Windows 20 років. У нас є подібна практика, яка існує давно. Я не можу порахувати, скільки разів ця практика врятувала моє бекон.

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

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

Коментар з номером дефекту дає мені місце для пошуку походження коду.

Так, так, система SCM робить багато, але не все. Ставтесь до них так, як і до будь-якого іншого коментаря, та додайте їх, де б не було внесено значні зміни. Розробник дивиться на ваш код 5+ років з того, як буде вам вдячний.

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

Не те, що я можу сказати.

Я роблю бризки TODO в своєму коді, коли я йду разом, і мета - видалити їх під час огляду.