Стандарт кодування для наочності: коментувати кожен рядок коду?

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

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

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

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

Враховуючи все це, чи можливо навіть написати хороші стандарти кодування, які захоплюють цю ідею? Одні, які будуть доречні в експертній оцінці, але не перетворяться на бездумну контрольну діяльність, яка створює нотатки не корисніші ніж: "Ви забули коментувати рядок 42".

Приклад виду коду, яке може вимагати це правило, якщо його розглядати як рядок у контрольному списку:

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

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

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

Відповідь Майкла Дюрранта - ІМХО непогана, але це буквально не відповідає на питання (як він визнав сам), тому я спробую дати відповідь, яка робить:

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

Враховуючи все це, чи можливо навіть написати хороші стандарти кодування, які захоплюють цю ідею?

Очевидно, ви можете написати контрольний список для оглядів свого коду , що містить такі питання

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

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

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

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

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

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

Розробники прагнуть писати гірший код. Вони використовуватимуть більш криптичні назви та структури, оскільки "це пояснено у коментарі - дивіться!".

Поміркуйте:

living_room_set = tables + chairs.

Тепер розглянемо:

set = tbls+chrs # Make the set equal to the table plus the chairs

Ви не тільки маєте і більш криптовалютні імена, і більше для читання, ви також повинні дивитися вперед-назад, дивитися на код, що таке набір? дивіться ліворуч на код, дивіться право на коментарі, що таке tbls, дивіться ліворуч на код, дивіться право на коментарі, що chrs, дивіться право на коментар. Юч!

Підсумок

Розробіть або вдосконалюйте стандарт коментування, якщо ви змушені займатися вашою нинішньою посадою як розробник (Як колишній програму COBOL я впевнено бачив великі!), Але витратили стільки вашого часу, енергії та пристрасті, сперечаючись проти коментування анти- шаблон за допомогою аргументів:

• Код і коментарі не синхронізуються один з одним, коли змінено лише один

• У коментарях може бути описано, що думає одна людина, але може бути неправильним, і таким чином приховати помилки

• Код стає важче читати

• Хороший код стає важче написати

• Схильність використовувати більш криптичні назви

• Зайві символи для читання в коді та коментарях

• Різні редактори використовують різні стилі

• Вимагає більш високого володіння англійською мовою, ніж просто кодування

• Займає час та ресурси та віднімає від довгострокового значення *

Плюс аргументуйте кращий код без таких коментарів, - адже є стандарт (!) - всі назви змінних повинні бути full_english_words - є один! Тому використовуйте енергію "стандартів" для стандартів добре написаного коду та тестів.

Однією з двох важких проблем є називання речей - не пропускайте проблеми з коментарями.

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

* код завтра

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

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

Якщо ви почнете додавати всілякі «найкращі практики» до стандарту кодування, ви просто в кінцевому підсумку повторите, що вже зазначено в кількох книгах. Просто придбайте "Чистий код", "Код завершений" та "Прагматичний програміст" у відповідного розробника, і дотримуйтесь стандартного кодування.

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

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

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

Оновлення

Моя відповідь у цитатах наголоси:

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

Проблема тут полягає в тому, що стандарт кодування - це саме те, що є стандартом . Надзвичайно суб'єктивні ідеї не повинні містити стандарт кодування . Це може бути посібник із кращих практик, але цей посібник не може бути використаний проти розробника під час перегляду коду. На мою особисту думку, стандарт кодування повинен бути максимально наближений до автоматизованого. У Code Reviews витрачено стільки часу, що сперечається щодо імен, пробілів, вкладок, дужок, коментарів тощо., Коли ВСЕ це можна автоматизувати. Навіть відповідь про tablesі chairsможе бути автоматизована. LINT'ers дозволяють виконувати словники, перевірки великої літери на поняття (змінна, функція, метод, клас тощо).

Навіть перевірка JavaDoc може бути реалізована роботом LINT'er до прийняття запиту на витяг. Дуже багато проектів з відкритим кодом роблять це точно. Ви подаєте свій Запит на виклик, код складається з файлу Travis-CI, включаючи статичний аналіз, і він повинен пройти всі стандарти кодування, які можна об'єктивно виразити. Ніяких людей не звучить "неправильно робити це" або "не надавати значення коментарям", або неправильний спосіб називати змінні тощо. Ці дискусії не надають ніякої цінності і найкраще залишити стороннім роботом, який може взяти на себе основну частину емоційного кодування.

Щоб відповісти на запитання, нам слід було б вирішити, як написати стандарт, який відповідає, як відповісти на таке запитання: Чи дав цей коментар значення? Стандарт кодування не може диктувати "значення" коментаря. Для цього людині стає необхідним пройти цей контрольний список. Просте згадування коментарів у стандарті кодування створює контрольний список, якого хоче уникати Оригінальний плакат.

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

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

Я заперечую, що стандарт кодування повинен залишатися максимально об'єктивним. Те, як змінні називаються об'єктивними IS. Їх можна легко перевірити в словнику щодо правильності написання, граматичної структури та обстановки. Все, що виходить за рамки цього, - це "підступний матч", який виграє людина з найбільшою силою або "б'ючи брови". Щось я особисто борюся з НЕ роблю.

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

Ось хороший лакмусовий тест. Якби ви були ТІЛЬКИ в проекті. Ви знали, що будете єдиним у проекті. Що було б у вашому стандарті кодування? Ви хочете, щоб ваш код у майбутньому був чистим, зрозумілим і зрозумілим для себе. Чи могли б ви ознайомитись із кодом щодо того, чому ви не коментували кожен рядок? Ви б переглянули кожен створений вами коментар до 100 файлів, які ви зареєстрували? Якщо ні, то навіщо змушувати інших?

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

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

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

У нас є два типи коментарів:

Машиночитані коментарі

Стилі коментарів, такі як Javadoc, JSDoc, Doxygen тощо, - це всі способи коментування публічного інтерфейсу, який надає набір коду. Цей інтерфейс може використовуватися лише одним іншим розробником (власний код для команди двох осіб), невідомою кількістю розробників (наприклад, JMS) або для цілого відділу. Цей код може бути прочитаний автоматизованим процесом, який потім створює інший спосіб читання цих коментарів, ala HTML, PDF тощо.

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

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

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

Цей тип коду викликає стільки проблем. Зазвичай він залишається без коментарів і пізніше виявляється новим розробником та "виправляється". Таким чином ламаючи все. Вже тоді коментарі є лише там, щоб пояснити, ЧОМУ насправді не завадити нічого зламати.

Не можна покладатися на коментарі

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

Це може здатися асиніном, але потерпіть мене. Який із цих двох рядків насправді має значення?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

У цьому прикладі важливо лише те, що ми поняття не маємо, що таке «n», не існує жодної перевірки на те, що n є 0 І навіть якщо вона була, ніщо не заважає розробнику поставити n = 0ПІСЛЯ чек на 0. Таким чином, коментар це марно і нічого автоматизованого ніколи цього не може наздогнати. Жоден стандарт не може цього наздогнати. Коментар, хоча досить (на деякі) не має жодного стосунку до результату продукту.

Тестова розробка

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

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

Документація приємна, коли ти намагаєшся зрозуміти, ЧОМУ хтось щось робив певним чином, однак я роками виявив, що документація зазвичай використовується для пояснення того, чому було зроблено щось «розумне», коли воно справді не потребувало писати саме так.

Висновок

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

Убік я допомагав близькому другу із завданням програмування. Його вчитель поставив вимогу, щоб кожен рядок був задокументований. Тож я можу бачити, звідки взявся б цей мислительний процес. Просто запитайте себе, що ви намагаєтеся зробити, і чи це правильно? Тоді запитайте себе; Чи є спосіб «грати» систему за допомогою цього процесу? Якщо є, то чи дійсно додає якусь цінність? Не можна автоматично писати одиничні тести, тести яких цей код відповідають певній специфікації, і якщо вони, можливо, це не буде поганою справою.

Якщо пристрій повинен працювати за певних умов, оскільки він буде знаходитись всередині людини, єдиний спосіб переконатись, що їх не збирається вбивати - це роки тестування, експертного огляду, випробувань, а потім НІКОЛИ ніколи не змінюючи код знову. Ось чому NASA / все ще використовує таке старе обладнання та програмне забезпечення. Якщо мова йде про життя чи смерть, ви не просто "зробите трохи зміни та перевірте це".

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

Є дві різні речі, на які ви натякаєтесь, коли говорите про коментарі. Вони не однакові, і відмінність важлива.

Документація розповідає про зовнішні біти фрагмента коду - його інтерфейс.

Зазвичай інструменти дозволяють вам читати їх самостійно, тобто ви одночасно не дивитесь на базовий код.

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

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

Коментарі у вихідному коді мають інше призначення. Вони там для людей, які дивляться на вихідний код. Вони насамперед описують реалізацію.

Коментарі завжди читаються серед основного коду.

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

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

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

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

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

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

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

Ви не можете зашифрувати стандарт коментування, оскільки не можете знати заздалегідь важливий коментар.

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

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

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

Нечитабельний код певною мірою неминучий. Тому що письменник занурений у контекст і побачить щось таке очевидне, коли це очевидно лише тоді, коли ви знаєте x, y або z.

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

Прокоментувати кожен рядок коду? Ні .

Мета інших правил, про які ви говорите, - саме уникнути цього.

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

Якщо ви коментуєте весь код, який не пояснює себе, ви подвоюєте кількість прочитаного, не даючи будь-якої додаткової інформації. Я не впевнений, чи окупиться таке резервування. Можна уявити рецензента, який каже, що 42 каже " display_error", тоді як у коментарі "відображається попередження". Але уявіть собі зміну коду. Зараз у вас є два місця для виправлення. Стає зрозуміло, що в цьому стилі є негативи копіювання та вставки.

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

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

1. Код є надто складним і його слід переробити у функцію з іменем із семантичним значенням для частини коду. Будь це комплекс ifабо частина алгоритму. (Або розумний однолінійний LINQ)

2. Якщо це неможливо спростити, ви не знаєте достатньої кількості ідіом мови.

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

Враховуючи все це, чи можливо навіть написати хороші стандарти кодування, які захоплюють цю ідею?

Щодо процесу. Наш стандарт дав неабияку оцінку рецензенту. Якщо припустити, що вони не шкідливі, це працює добре.

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

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

Також абсолютів не було . Хоча ми були невеликою групою. Легко знайти консенсус у групі 5.

Питання:

Враховуючи все це, чи можливо навіть написати хороші стандарти кодування, які захоплюють цю ідею? Оні, які будуть доречні в експертній оцінці, але не перетворяться на бездумну контрольну діяльність, яка створює нотатки не корисніші ніж: "Ви забули коментувати рядок 42".

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

Читач цього коду, з вашого прикладу, повинен знати, що exit()вийде з програми - таким чином зробивши коментар зайвим:

/* Exit the application */
exit();

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

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

PEP 8 Python (посібник зі стилів для Python у стандартній бібліотеці CPython) пропонує наступне керівництво для вбудованих коментарів:

Використовуйте вбудовані коментарі економно.

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

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

x = x + 1                 # Increment x

Але іноді це корисно:

x = x + 1                 # Compensate for border

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

border_compensation = 1
compensated_x = x + border_compensation

Самостійне документування коду - це не нова ідея .

Повернутися до актуального питання:

Враховуючи все це, чи можливо навіть написати хороші стандарти кодування, які захоплюють цю ідею?

Я вважаю, що керівництво та приклад PEP 8 демонструє хороший стандарт кодування, який фіксує цю ідею. Так що так, я вважаю, що це можливо.

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

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

редагувати ----

Просто для уточнення. Я не впадаю в коментарі проти tdd vs одиничні тести, які найкращі. Або запропонувати коментар за рядком - це добре / погано

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

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

тобто коментарі - це пояснення мети коду, що також є специфікацією

Враховуючи все це, чи можливо навіть написати хороші стандарти кодування, які захоплюють цю ідею? Оні, які будуть доречні в експертній оцінці, але не перетворяться на бездумну контрольну діяльність, яка створює нотатки не корисніші ніж: "Ви забули коментувати рядок 42".

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

Моє правило №1 - "Не документуйте очевидного". Правило №2 - "Написати очевидний код".

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

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

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

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

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

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

ІМХО це повинно робити і те, і інше. Коментувати кожен рядок нерозумно, тому що ви закінчуєтесь такими рядками

  i++;    /* Increment i */

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

OTOH, якщо ви пишете хороший блок коментарів на чолі функції (або будь-яке групування є логічним), описуючи і те, що має бути виконано, і як, якщо це менш очевидно, у вас є щось корисне. Якщо ви мене, ви можете навіть включити код LaTeX для відповідних рівнянь або посилання на документи, наприклад, "Це реалізує схему ВЕНО для вирішення рівнянь Гамільтона-Якобі, як обговорювалося в ..."

Настав час повернути потокові діаграми! (не дуже, але зачекай на хвилину)

Днями я знайшов свій старий шаблон блок-схеми. Я використовував це лише для домашніх завдань та жартів (ти мусиш любити гарну нерозумну схему). Але навіть до цього часу більшість комерційних програмістів, які все ще використовували діаграми потоків, автоматично генерували їх з коду (що повністю підриває початкове призначення блок-схеми, яка повинна була бути помічником у написанні кращого коду та була досить корисною в машинному коді. Однак з мовами вищого рівня блок-схема змінилася з коси на хобі. Чому? Абстракція блок-схеми була такою ж, як і в коді. Показані коментарі є хоббітом, оскільки вони знаходяться на тому ж рівні абстракції, що і код. Хороші коментарі знаходяться на різному рівні абстрагування, ніж код. Найпростіший спосіб зробити це - використовувати коментарі, чому тоді, коли код обробляє що.

Я відповім на запитання так:

Враховуючи все це, чи можливо навіть написати хороші стандарти кодування, які захоплюють цю ідею?

Так. WYSIWYG. Хороший стандарт кодування буквально " читачеві зрозуміло, що робить наступний код і чому ".

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

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

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

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

Другий стандарт, який повинен бути чіткий, - це "екстрена перевірка в 2 години ранку".

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

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

Ця відповідь охоплювала більшість питань, проте є одна важлива річ.

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

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

Багато з існуючих відповідей добре деталізовані, але я вважав важливим відповісти:

... [коментарі], які будуть актуальними для експертної оцінки, але не перетворяться на бездумну діяльність контрольного списку ...

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

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