Я побачив багато номерів випусків із коментарів коду jQuery . (Насправді в коді jQuery було 69 номерів номерів.) Я думаю, що це було б хорошою практикою, але я ніколи не бачив жодних вказівок.
Якщо це хороша практика, які вказівки для цієї практики?
Я побачив багато номерів випусків із коментарів коду jQuery . (Насправді в коді jQuery було 69 номерів номерів.) Я думаю, що це було б хорошою практикою, але я ніколи не бачив жодних вказівок.
Якщо це хороша практика, які вказівки для цієї практики?
Відповіді:
Взагалі я б не вважав це доброю практикою. Але у виняткових випадках це може бути дуже корисно, а саме тоді, коли код повинен зробити щось неінтуїтивне, щоб виправити складну проблему, і без жодних пояснень існує ризик, що хтось може захотіти «виправити» цей дивний код і тим самим зламати його , тоді як пояснення міркувань призведе до величезного коментаря, який дублює інформацію з проблеми.
Я думаю, що достатньо додати номер проблеми до повідомлення про фіксацію, коли ви здійснюєте відповідне виправлення у своїй системі управління джерелом.
Наприклад:
Помилка № 203: після 30 секунд з’єднання з базою даних більше не вичерпуються.
Я вважаю, що додавання номерів випусків, імен розробника або дат, які були внесені в код, просто забруднює базу коду і справді повинна керуватися зовнішньою системою управління джерелами.
Я повністю не згоден з іншими тут плакатами!
Зауваження до коду із відстеженням посилань можуть стати величезною підмогою для програмування технічного обслуговування.
Якщо я відстежую помилку і наближаюся до області коду, побачити, що вона нещодавно була змінена і мати посилання на контекст зміни, - це відправлення богом.
Так, у нас є контроль вихідного коду, але перевіряти файли та модулі можна досить повільно. Ви хочете, щоб ці речі вискочили на вас за останні зміни.
Я б, мабуть, зневажив їх, бо бачу справді старі в базі коду, але дуже мало уваги до того, щоб утримувати новіші та багато потенційно заощадженого часу розробника, якщо ви їх розумно використовуєте.
Я фактично думаю, що ці невеликі посилання на вашу систему відстеження помилок є кращими, ніж детальні коментарі до коду.
git gui blame <filename>надається дуже швидкий графічний інтерфейс для перегляду історії коду, якщо ви використовуєте git. Використання інструменту для поєднання коментарів до коду з історією дозволяє набагато кращу документацію для коду, ніж будь-які вбудовані коментарі. Тобто, якщо ви переймаєтеся написанням хороших повідомлень про фіксацію (хороше повідомлення про фіксацію має бути приблизно рівним електронному повідомленню, яке пояснює, чому саме цей патч слід застосовувати).
Якщо ви підписуєтесь на політику "Чистого коду", то, ймовірно, потрібно запитати себе, чи є хороша практика взагалі додавати коментарі. Якщо код можна уточнити лише за допомогою коментаря, тоді обов'язково додайте його, інакше ви зможете легко зрозуміти, що робить ваш код, просто прочитавши його (за умови, що ви використовуєте розумні імена для своїх змінних, методів тощо).
Незалежно від вашої особистої думки щодо того, чи є коментування доброю практикою чи ні, коментар повинен містити інформацію, яка має пряме значення для коду, на який йдеться. У цьому випадку питання полягає в тому, чи додавання номера виду додає значення коду. Проблема, яку я бачу при додаванні номера випуску, полягає в тому, що ви можете мати розділ коду, який може бути сильно змінений, щоб задовольнити декілька проблем, і через деякий час неможливо буде правильно визначити, які зміни стосуються конкретної проблеми. Подальші проблеми, наприклад, можуть зажадати реконструкції коду, що стосується попередніх випусків. Це, мабуть, крайній приклад, проте він показує, як номери випусків у коментарях у коді можуть виявитися досить марними.
Якщо ви могли б гарантувати, що ситуація, яку я тільки що описав, ніколи не відбудеться, я все-таки стверджую, що сам номер випуску все ще є досить марним без опису того, про що йдеться, і все ж, вся ця інформація дійсно належить вашому система відстеження випусків, і її потрібно дублювати. Краще відзначити номер проблеми у вашій системі контролю версій як коментар. Перевага полягає в тому, що ви можете порівнювати версії та бачити зміни коду, що стосуються конкретної проблеми, тоді як сам номер випуску надає вам потрібний ідентифікатор, якщо ви хочете переглянути причину зміни коду.
Зважаючи на це, я б припустив, що це не дуже хороша практика, тому що додавання номерів випусків до коментарів у вашому коді.
Я думаю, що це найкраща практика звернутися до питання для подальшого читання, даючи коротке пояснення у самому коментарі.
Я, як правило, додаю коментарі, лише якщо в цьому фрагменті коду є щось тонке або неінтуїтивне. Оскільки деякі тонкі питання неможливо пояснити повністю за декілька рядків, і я не хочу додавати десятки рядків коментарів, я б додав короткий коментар із описом того, чого намагається досягти, і посилаюся на проблему деталі.
Наприклад:
// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details
Де випуск 123 описує, як може виглядати ця атака, і чому новий код захищений від атаки.
Або:
// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.
Основна проблема при введенні номерів випуску у джерело полягає в тому, що у вас зараз є зовнішня довідка. Тому ви повинні бути впевнені, що ви не втратите проблему.
Включення номера випуску у повідомлення про фіксацію може бути дуже корисним, коли ваш вихідний код підключається до постійної інтеграції. Такі програми, як TeamCity, витягнуть цю інформацію та дозволять покращити звітність.
З урахуванням сказаного я не на 100% впевнений, що це випливає з коментарів до коду. Включення номерів випусків у код добре працює, якщо номери випусків зберігаються (наприклад, ви не змінюєте трекер випусків) і у вас не так багато питань для даного проекту.
Це, мабуть, корисніше, якщо ви опишете проблему та рішення, тому наступному розробникові не потрібно шукати номер проблеми. Компілятор або міні-програвач просто видалить ваші коментарі до виходу коду в дику природу, тому не повинно бути ніякого впливу на кінцевий результат.