Чи добре зберігати коментарі помилок у коді?

Моя команда використовує чіткі регістри як контроль версій. Проект, над яким я працюю, не розпочався 7-8 років тому. Протягом усього періоду життя проекту у нас було декілька пакетів виправлень помилок виправлень тощо. Проблеми відстежуються за допомогою системи відстеження помилок, і більшість людей, які працюють над виправленнями помилок, дотримуються процедури додавання коментаря у START / Блок END із датою, автором, ідентифікатором помилки тощо

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

Якої найкращої практики слід дотримуватися?

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

Проблема з додаванням помилки в якості коментаря до коду полягає в тому, що ви не отримаєте повну історію. Якщо я бачу прекрасно шматок коду з тегами «це виправлення бага - бла », моя перша реакція була б сказати : «Ну і що?». Код є, він працює. Єдине, що мені потрібно знати, щоб підтримувати код, - це коментар, який говорить мені, що він робить.

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

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

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

Погана практика. Коментарі застаріють і захаращують код. Інформація все ще доступна в історії версій системи SCC, якщо це необхідно.

Звучить як погана практика. Що робити, якщо ваша організація вирішить перейти на іншу систему відстеження помилок? Не прив'язуйте виріб занадто щільно до інструментів, якими ви користуєтесь. Замість того, щоб посилатися на конкретні ідентифікатори помилок, а причини, чому код виглядає так, незрозумілі, мотивуйте своє дизайнерське рішення коментарями до коду.

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

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

Просто для додання того, що Dyaster et al. сказали, хоча JIRA має дуже хороші здібності відображати зміни, пов'язані з виправленнями помилок, найкраще найкраще місце для документування виправлення - у тестовому випадку. Якщо код не зрозумілий без коментаря із зазначенням того, яку помилку виправлено, це "запах коду". Однак, якщо у вас немає часу на очищення запаху, коментар повинен посилатися на тестовий випадок, де має бути набагато очевидніше, чому код робить те, що робить. Якщо у вас немає часу написати тестовий випадок з поясненням виправлення помилки, помилка ще не була виправлена, її просто відклали.

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

Крім того, ви можете використовувати команду blame / annotate / хвалу для вашої системи контролю версій, щоб допомогти замінити ці коментарі. Потім, коли ви запускаєте щось на кшталт:

vcs blame file.ext

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

Хороші системи VCS дозволять вам ігнорувати пробіли під час підрахунку того, хто змінив лінію.

Я не знаю, що Clear Case має для цієї функції.