Код самодокументації проти Javadocs?

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

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

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

Які найкращі практики для цього? Де ви проводите межу між кодом самодокументування та javadocs?

Код самодокументування (та коментарі до коду) та коментарі Javadoc мають дві дуже різні цільові аудиторії.

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

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

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

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

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

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

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

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

слідкувати за аудиторією

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

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

• Це саме так з документацією JDK . Згадайте, Sun / Oracle витрачав багато зусиль на це, і, здається, вони мають хорошу окупність в документах API, які багато використовуються громадою.

Тепер це ваш випадок? Якщо ні, подумайте двічі, чи виправдані зусилля, вкладені в javadocs.

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

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

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

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