"Коментарі - це кодовий запах" [закрито]

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

Тільки якщо коментар описує, що робить код.

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

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

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

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

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

Очевидно, ваш колега недостатньо досвідчений.

Коментарі повинні пояснювати, чому, а не як.

Howкоментарі типу зазвичай краще вирішувати за допомогою рефакторингу. Особисто я зазвичай уникаю коментарів на користь рефакторингу.

Перед:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

після:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

Я оголошую вашого колегу єретиком! Де мої єретичні спалювальні черевики?

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

Деякі фактичні коментарі до коду, над яким я працюю:

    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

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

Чого слід абсолютно уникати, це "надмірність коду коментування" (коментарі, які нічого не додають до коду):

i++; // Increment i by 1

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

Але в деяких обставинах коментарі можуть стати гарною підмогою у читанні коду:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

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

Категорично визначати метод або процес як "кодовий запах" - це "запах завзятості". Термін стає новим "вважається шкідливим".

Будь ласка, пам’ятайте, що всі подібні речі повинні бути настановами.

Багато інших відповідей дають хороші поради щодо того, коли коментарі є виправданими.

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

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

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

У деяких випадках жодна кількість хороших імен, рефакторингу тощо не може замінити коментар. Подивіться на цей приклад у реальному світі (мова - Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Дивно виглядає, чи не так? Можливо, помилка копіювання-вставки? Крики про помилку?

Тепер те саме з коментарями:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler

Основне питання тут - значення терміна "кодовий запах".

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

Це не значення терміна!

Метафора кодового запаху походить від Wards Wiki , і вони підкреслюють:

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

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

Саме це означає, що коментарі мають запах коду.

EDIT: Я просто натрапив на ці дві статті, що пояснює це краще за мене:

• Вибачення у коді
• Потрібні коментарі

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

Хороша ідея мати правильні коментарі - почати з написання коментарів.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Це дозволяє легко витягувати методи, щоб навіть позбутися від коментарів,
просто нехай код розповість про це ! Подивіться, як це дуже красиво переписати (вирізати / вставити):

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

Для речей, які не можна розділити, просто не вилучайте методи та вводите код під коментарями.

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

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

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

// Dear me in the future. Please, resolve this problem.

або

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.

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

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

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

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

Самс навчить себе візуальним C # 2010 за 24 години , стор 348-349.

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

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

Серед почесних згадок є анти-шаблон:

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

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

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

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

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

Коментарі, які є, тому що ви знаєте, якщо ви не залишите коментар, хтось знову зробить ту саму помилку - це запах.

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

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

Я відповім власним питанням. Чи можете ви знайти помилку в коментованому коді нижче?

tl; dr: Наступна особа, яка підтримує ваш код, може бути не такою богоподібною, як ви.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55

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

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

Також коментарі дуже корисні, додаючи «застереження» на кшталт «Будьте обережні! Якщо формат вводу не ASCII, цей код доведеться змінити!»

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

Справжні програмісти не пишуть коментарів - якщо важко було написати, важко було б прочитати

Досить старший запах придумує.

Я думаю, що коментування коду отримує дуже поганий початок життя. Я не знаю про ці дні, але коли мене в школі вперше навчали програмуванню, я отримав завдання "Напишіть програму, яка друкує цифри від одного до десяти на окремих рядках. Обов'язково прокоментуйте свій код". Ви отримаєте відмітку, якщо ви не додали коментарів, оскільки коментування коду - ДОБРО.

Але що тут говорити про такий тривіальний процес? Отже, ви закінчите писати класику

i++; // add one to the "i" counter.

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

Коментування коду - це НЕ ДОБРЕ. Це НЕОБХІДНЕ РЕЧІ, і Томас Оуенс у верхній відповіді дає чудове пояснення ситуацій, у яких це необхідно. Однак такі ситуації рідко виникають у домашніх завданнях.

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

Звичайно коментарі - запах коду ...

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

"Зробити це!" каже ваш керівник проекту.

Ви відповідаєте: "Це неможливо зробити".

Вони кажуть: "Тоді ми знайдемо когось іншого".

Ви кажете: "Добре, ну, може, це можна зробити".

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

1) Ті, хто це робить, або полегшують власну роботу, документуючи для подальшої довідки, коментуючи невдалі підпрограми, які не працювали (запах не видаляє їх після знаходження тієї, що працює.), Або розбиває код з коментарем форматування, сподіваємось, полегшити читання чи розуміння. Серйозно, я не можу їх звинуватити. Зрештою, вони хапаються, і тоді ви маєте це: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

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

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

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

1. Вам потрібно щось робити в кожному конкретному випадку, і для цього немає хорошої логіки.
2. Код, швидше за все, зміниться через рік-два, коли закони будуть змінені, і ви хочете знайти його знову швидко.
3. Хтось редагував код раніше, оскільки не розумів, що робить код.

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

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

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

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

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

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

Ці коментарі зазвичай мають форму на кшталт:

//xxx what the heck is this doing??

або

// removed in version 2.0, but back for 2.1, now I'm taking out again

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

Ось моє правило:

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

Навчіть свого колегу про техніку грамотного програмування .

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

Приклади хороших коментарів:

// Я думаю, що це в см. Потрібне подальше розслідування!

// Це розумний спосіб робити X

// Список гарантовано не порожній