Чи вважаються коментарі формою документації?

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

Не було б це:

$foo = "bar"; # this is a comment
print $foo; # this prints "bar"

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

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

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

Вони є формою документації, але пам’ятайте, що документація на очах у глядача….

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

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

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

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

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

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

Я знаю, ти це мав на увазі як відкидний приклад, але подібні речі

print $foo; # this prints "bar"

не корисно; це просто додає візуальної безладу. Не документуйте очевидного.

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

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

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

Ми автори. І одне про авторів - це те, що вони мають читачів. Дійсно, автори відповідають за те, що вони добре спілкуються зі своїми читачами. Наступного разу, коли ви пишете рядок коду, пам’ятайте, що ви автор, пишете для читачів, які оцінять ваші зусилля.

... співвідношення часу, витраченого на читання та написання, значно перевищує 10: 1. Ми постійно читаємо старий код як частина зусиль для написання нового коду.

Іншими словами, чи ваш код без пояснення документації не пояснює? Для нього немає встановленого правила (якщо ви не працюєте на когось, як Microsoft, документація якого доступна загальнодоступному), це здебільшого зводиться до допомоги майбутньому читачеві коду, який часто є вами.

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

Чому , ймовірно , не повинно бути в коді, він повинен бути де - то ще , як відставання продукту, який прив'язаний до скоєння коментарів з сюжетними ідентифікаторами , які можна знайти в в журналі змін або назва філії.

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

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

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

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

3) Для скриптів варіант --help. Ось тут ви можете зірватись на doc. Дотримуйтесь прикладів, передбачте, що користувачеві знадобиться.

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