Найкращі практики написання коментарів та документації

Коментувати сьогодні простіше, ніж будь-коли. У Java є кілька приємних прийомів пов'язування коментарів до класів, і Java IDE добре допомагає робити оболонки коментарів для вас. Такі мови, як Clojure, навіть дозволяють додавати опис функції в сам код функції як аргумент.

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

Зокрема, мене тут цікавить Java / Clojure / Python, але відповіді не потребують мови.

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

І ще важливіше: чи прийняті там "політики коментування" чи стратегії? Там є багато порад щодо кодування - але як щодо "як коментувати?"

• Імена / документація повинні говорити про те, що ви робите.

• Впровадження повинно сказати вам, як ви це робите.

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

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

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

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

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

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

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

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

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

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

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

Існує добре відома методика - вона називається "перегляд коду" і має сестру на ім'я "парне програмування". Тут не чекайте нічого "автоматизованого".

І ще важливіше: чи прийняті там "політики коментування" чи стратегії? Є багато порад щодо того, як кодувати ---, а як щодо "як коментувати?"

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

Характерне для Java одне джерело, яке мені сподобалося, - це як писати коментарі докуму Oracle для інструменту Javadoc :

Цей документ описує посібник зі стилів, теги та умовні позначення, які ми використовуємо в коментарях до документації для програм Java, написаних на Java Software, Sun Microsystems.

І Пункт 44: Напишіть коментарі док для всіх відкритих елементів API :

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

від ефективної Java 2nd Edition .