У мене був пошук, але я не знайшов того, що шукав, будь ласка, не соромтеся зв’язати мене, якщо це питання вже задавали.

Раніше цього місяця це повідомлення було зроблено:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/

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

У наведеному прикладі

// Get the extension off the image filename  
$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

Автор сказав, що до цього коду слід дати коментар, моя особиста думка полягає в тому, що код повинен бути викликом функції, який є описовим:

$extension = GetFileExtension($image_filename);

Однак у коментарях хтось насправді зробив саме таку пропозицію:

http://net.tutsplus.com/tutorials/php/why-youre-a-bad-php-programmer/comment-page-2/#comment-357130

Автор відповів, сказавши, що коментатор "один із тих людей", тобто поганий програміст.

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

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

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

Звичайно, як зазначав @Niphra, завжди варто двічі перевірити, чи те, що я вважаю чистим, дійсно зрозуміле оточуючим. Однак і це питання практики. Ще в університеті я написав загадкові фрагменти коду просто завдяки використанню дивних і смішних імен для всіх кодових утворень, за моєю примхою. Поки мій вчитель не відкинув одне із моїх завдань, ввічливо зазначивши, що він не міг зрозуміти, який модуль був головним :-) Це був хороший урок, тому я намагався зосередитись на написанні все більш читабельного коду з тих пір. Сьогодні я навряд чи отримую скарги від товаришів по команді.

Ви не повинні документувати, що робить код, але ви повинні документувати, чому він це робить.

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

Всі інші коментарі можна сміливо позбутися.

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

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

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

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

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

Аргументи, що перекриваються

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

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

Самоописуючий код

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

Більше коментарів

• Коментарі легше читати, ніж код. Звичайна англійська мова краще описувати щось.

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

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

Для демонстрації в книзі « Чистий код» код розбивається на численні менші методи, які викликаються лише один раз. Методи створюються з єдиної причини документування коду (і простішого TDD). Це призводить до функціонального пекла . Код є менш читабельним, ніж був спочатку, і під час рефакторингу, не було думки щодо інкапсуляції коду для багаторазового використання.

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

"Мені шкода, але твій той хлопець".

Цікаво, чому він не любить коментувати: P

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

Розглядайте грамотне програмування як екстремальний стиль.

Короткий, кращий і правильний відповідь

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

Значно краща відповідь, ніж коментарі, слід використовувати лише для пояснення "чому" , що коментарі повинні:

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

Пояснення резервного копіювання

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

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

Ще одна антидіаграма - це надмірне використання функцій для коментування коду. Добре названі функції є важливою частиною кодової документації, але іноді програмісти відокремлюють 2-3 рядки коду, які ніколи більше не використовуватимуться у функції для цілей документації. Чому надмірне використання функцій краще, ніж надмірне використання коментарів? Використання таких функцій - це те саме, що використання виразів GOTO - це створює код спагетті, який може зазнати біль.

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

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

Що ж, з кодом самодокументування полягає в тому, що в рамках цієї функції ви знайдете:

$pieces = explode('.', $image_name);  
$extension = array_pop($pieces);  

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

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

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

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

$ extension = GetFileExtension ($ image_name);

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

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

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

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

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

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

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

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

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

EBITDA

і ні

Акціонерний капітал попереднього інтересуТакси Оцінка та Амортизація

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

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

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

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

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

//
// iterative version
//
Node* ReverseList( Node ** List ) 
{

  Node *temp1 = *List;
  Node * temp2 = NULL;
  Node * temp3 = NULL;

  while ( temp1 )
  {
    *List = temp1; //set the head to last node 
    temp2= temp1->pNext; // save the next ptr in temp2
    temp1->pNext = temp3; // change next to privous
    temp3 = temp1;
    temp1 = temp2;
  }

  return *List;
}

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

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

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

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

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

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

Простіше кажучи, не пишіть, що ви коментарі КОДУЙТЕ їх

Ознайомтеся з кодом 2-го видання, стор. 128-129.

Абстрактні типи даних позбавлять вас від цієї загадки. Самодокументування коду - це шлях. Коментарі можуть бути корисними, але є

суб'єкти реального світу, а не низькорівневі реалізації

ви можете уникати використання коментарів.

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

Коментарі дуже корисні, коли вони інтерпретують IDE так, як працює Delphi 2009+ або JavaDoc, але це скоріше структурована мова розмітки, тому в певному сенсі ви програмуєте свою документацію, яка дуже розумна.

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

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

Якщо ви просто пам’ятаєте про це при кодуванні / програмуванні?

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

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

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

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

Перевірте http://thedailywtf.com, у них є безліч гумористичних, але справжніх історій про програміста, який просто не зробив належну ретельність.