Що таке код самодокументування та чи може він замінити добре задокументований код? [зачинено]

У мене є колега, який наполягає на тому, що його код не потребує коментарів, це "самодокументація".

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

Допоможіть зрозуміти його точку зору.

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

Можливо, це лише мої власні обмеження, але я не бачу, як це може бути хорошою практикою.

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

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

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

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

• пише коментарі до документації (Doxygen, JavaDoc, XML коментарі тощо) для кожного класу, члена, типу та методу AND
• чітко коментує будь-які частини коду, які не є самодокументованими І
• пише коментар до кожного блоку коду, який пояснює наміри або те, що код робить на більш високому рівні абстракції (тобто знайти всі файли розміром більше 10 Мб замість циклу через усі файли в каталозі, перевірити, чи розмір файлу більше 10 МБ, прибутковість, якщо справжня )

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

Ну, оскільки мова йде про коментарі та код, давайте розглянемо якийсь фактичний код. Порівняйте цей типовий код:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

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

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

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

/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

І потрібна остаточна версія коду як документації з нульовими коментарями:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

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

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

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

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

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

Хтось одного разу сказав

1) Пишіть лише коментарі для коду, який важко зрозуміти.
2) Намагайтеся не писати код, який важко зрозуміти.

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

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

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

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

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

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

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

Я забуваю, звідки я це взяв, але:

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

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

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

print "Hello, World!"

і так це:

factorial n = product [1..n]

і так це:

from BeautifulSoup import BeautifulSoup, Tag

def replace_a_href_with_span(soup):
    links = soup.findAll("a")
    for link in links:
        tag = Tag(soup, "span", [("class", "looksLikeLink")])
        tag.contents = link.contents
        link.replaceWith(tag)

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

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

Самодокументування коду є хорошим прикладом "DRY" (не повторюй себе). Не дублюйте інформацію в коментарях, які є або можуть бути в самому коді.

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

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

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

І т.д.

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

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

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

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

самодокументування коду + необхідні коментарі пройдуть довгий шлях до допомоги людям у колективах.

В порядку:

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

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

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

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

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

Просто моя щіпка солі ...

Для одного розглянемо наступний фрагмент:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

У цьому прикладі у вас є 5 рядків коментарів на 3 рядки коду. Ще гірше - коментарі не додають нічого, чого ви не можете побачити, прочитавши код. Якщо у вас є 10 подібних методів, ви можете отримати «коментар сліпоти» і не помітити одного методу, який відхиляється від шаблону.

Якщо, звичайно, краща версія була б:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

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

Різниця між "що" і "як".

• Ви повинні документувати "що" рутина.
• Не слід документувати "як" це робиться, якщо тільки спеціальні випадки (наприклад, посилання на певний алгоритм). Це має бути задокументовано самостійно.

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

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

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

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

Однак такий "код самодокументування" ніколи не замінить коментарі. Іноді код є занадто складним, і самодокументування коду недостатньо, особливо на шляху ремонту.

Я колись мав професора, який був твердо вірю в цю теорію. Насправді найкраще, що я коли-небудь пам’ятаю, як він говорив: «Коментар - це для сіссі»
Спочатку це сприйняло всіх нас зненацька, але це має сенс.
Однак ситуація полягає в тому, що, хоча ви, можливо, зможете зрозуміти, що відбувається в коді, але хтось із менш досвідчених, ви можете прийти за вами і не зрозуміти, що відбувається. Це коли коментарі стають важливими. Я багато разів знаю, що ми не вважаємо, що вони важливі, але дуже мало випадків, коли коментарі зайві.

Я здивований, що ніхто не спричинив " Грамотне програмування ", методику, розроблену в 1981 році Дональдом Е. Кнутом із TeX та славу "Мистецтво комп'ютерного програмування".

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

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

Я знайшов приклад у мережі Інтернет: http://moonflare.com/code/select/select.nw або HTML-версія http://moonflare.com/code/select/select.html

Якщо ви можете знайти книгу Кнут у ній у бібліотеці (Дональд Е. Кнут, Літературне програмування, Стенфорд, Каліфорнія: Центр вивчення мови та інформації, 1992 р., Записки лекцій CSLI, № 27.), ви повинні прочитати її.

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

Я хотів би запропонувати ще одну перспективу для багатьох вагомих відповідей:

Що таке вихідний код? Що таке мова програмування?

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

Чи зможете ви прочитати те, що ви пишете?

Вихідний код написаний не людською мовою. Це було випробувано (наприклад, FORTRAN), але це не зовсім успішно.

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

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

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

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

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

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

Для мене це правила, яких я намагаюся дотримуватися:

• Код повинен бути максимально легким і зрозумілим для читання.
• У коментарях повинні бути підстави для прийнятих дизайнерських рішень, як-от: чому я використовую цей алгоритм, або обмеження, які має код, як-от: не працює, коли ... (це слід обробляти в договорі / твердженні в коді) (зазвичай в межах функції / процедури).
• Документація повинна перераховувати використання (виклик конвертацій), побічні ефекти, можливі зворотні значення. Його можна дістати з коду за допомогою таких інструментів, як jDoc або xmlDoc. Тому зазвичай це знаходиться поза функцією / процедурою, але близьке до коду, який він описує.

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

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

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

Бути в змозі визначити, що код робить X з швидкого погляду - це набагато простіше, ніж вміти визначити, що код не робить Y. Він повинен документувати Y ...

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

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

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

Редагувати: Я (і, можливо, всі інші), мабуть, маю б положення про те, що додаток для обробки цифрових сигналів (DSP) слід дуже добре коментувати. Це головним чином тому, що програми DSP по суті є 2 для циклів, що живляться масивами значень і додає / помножує / і т. Д. Зазначені значення ... щоб змінити програму, ви зміните значення в одному з масивів ... потрібно пару коментарів, щоб сказати, що ви робите в цьому випадку;)

Під час написання математичного коду я іноді вважаю корисним писати довгі коментарі до есе, пояснюючи математику, нотаційні умовності, які використовує код, і як це все поєднується. Ми говоримо сотні рядків документації тут.

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

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

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

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

Гарне моделювання домену 
+ хороші імена (змінні, методи, класи) 
+ приклади коду (одиничні тести із випадків використання) 
= програмне забезпечення для самостійного документування 

Кілька причин, чому додаткові коментарі на додаток до коду можуть бути зрозумілішими:

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

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

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

BisectionSearch

BinarySearch

BinaryChop

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

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

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

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

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

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

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

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

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

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

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

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

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