Хороша ідея помістити номери помилок у коментарі на початку вихідного файлу? [зачинено]

Чи є гарною практикою розміщення номерів помилок у самому файлі у коментарі до заголовка?

Коментарі будуть виглядати приблизно так:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

Це здається корисним, але чи вважається це поганою практикою?

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

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

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

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

І якщо код змінився таким чином, що немає спокуси зателефонувати foo()безпосередньо, видаліть цей коментар. Це лише роздратує і підірве код.

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

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

Немає.

Це робили люди до того, як вони використовували систему контролю версій (тобто коли вихідний код був лише резервним копієм у zipfiles).

Це, ІМХО, дуже погана ідея. Після редакції № 100 ви отримаєте 90% коментарів та 10% код. Я б не вважав це чистим і читабельним.

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

Я бачу, що всі виступають проти цієї ідеї і дали історичну причину (до епохи контролю над джерелами), чому люди це робили.

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

Так, це захаращує код, але це допомагає знайти причину, чому цей фрагмент коду є.

Одним із пунктів тесту Джоеля є

У вас є база даних про помилки?

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

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

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

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

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

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

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

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

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

Особисто я думаю, що є місце і для інструментів, і для журналу коду.

Я знаю , що Git не робить це і проста відповідь «навіщо б він туди?»

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

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

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

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

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

Якщо ви хочете добре прочитати цю тему, рекомендую четверту главу чистого коду .

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

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

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

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

Будь-яка інформація про помилку, безпосередньо пов’язану з фрагментом коду, стає нерелевантною, коли цілісність усієї зміни змінюється послідовними виправленнями.

Раніше було додати інформацію до підсумків функцій, коли нам довелося покладатися на зовнішні інструменти (скажімо, javadocs) для створення приміток до випуску з коду. Здебільшого марно або надмірно сучасні засоби контролю версій.

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

Я точно не ставлю таку інформацію на початку файлу - зазвичай така річ належить до системи квитків.

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

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

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

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