Посібник для початківців щодо написання коментарів?

27

Чи є остаточний посібник із написання коментарів до коду, спрямованих на початківців розробників?

В ідеалі він охоплює, коли коментарі слід (і не повинні) використовувати, а також які коментарі повинні містити.

Не коментуйте, що ви робите, але ЧОМУ ви це робите.

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

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

Оновлення : Окрім відповідей тут, я вважаю, що ця відповідь на інше питання є дуже актуальною.

language-agnostic comments

— Камерон
джерело

Я думаю, що ми швидко рухаємось у світ, де люди більше не коментують. На краще (скоріше) на гірше. Спритний

— MK01

1

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

— Камерон

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

— MK01

див. також: "Коментарі - це запах коду"

— gnat

38

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

Тому не документуйте, що робить код. Код про самодокументування повинен вирішувати це. Документ ЧОМУ ви це робите. ЧОМУ зазвичай пов'язані з діловими правилами або архітектурою, і вони не змінюватимуться часто і залишаються несвіжими на ШТО. Корпусні кейси документа. Винятки з документа Проектні рішення документа. І найголовніше задокументувати ті проектні рішення, які ви розглядали, але вирішили не застосовувати (і документуйте ЧОМУ ви вирішили їх використовувати).

2

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

— CaffGeek

2

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

— Ерік Гідрік

10

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

— Боб
джерело

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

— CVn

Код може говорити лише про те , як , ні чому або чому ні . Для цього вам потрібні коментарі.

7

Як було сказано, Code Complete має різні рекомендації щодо написання коментарів. Коротше кажучи, це PDL і його можна підсумувати як:

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

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

На GameDev.net є посилання [яке пояснює PDL] [1], якщо ви не хочете знайти книгу.

— Екстракун
джерело

5

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

— Бінарний занепокоєння

1

Також коментарі псевдокоду підкажуть вам, що повинен робити код. Код повинен вам це сказати. Псевдо-код не скаже вам, чому код це робить. -1 чувак, вибачте, але я не можу погодитися з другим моментом, часи змінилися.

— Бінарний занепокоєння

1

Не сперечатися, але більше пояснень - псевдокод пояснює наміри написаного вами коду. Це означає, що коментар стосується не детальних відомостей про впровадження (наприклад, "Додати x у верхню частину стека"), а скоріше того, що повинен робити код (наприклад, "Зробити вікно" перед усім "). Як ви справедливо зазначали, вам потрібно перемістити коментарі з кодом. Я не погоджуюся з кодом і може вам сказати, що робить код - весь час. Навіть якщо корисний / точний коментар (якщо мені вдасться це добре написати!) Проходить довгий шлях. Зрештою, все ж ІМХО.

— Екстракун

3

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

6

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

— Шахзеб
джерело

1

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

— Кевін
джерело

1

Так, так ;-) Це не особливо корисна порада - можливо, це повинен був бути коментарем?

— Камерон

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

0

Мені дуже подобається, як Еван Тодд узагальнює свій погляд на єдині корисні категорії коментарів ( цитуючи з його блогу ):

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

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

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

— Камерон
джерело