Ви повинні документувати все або просто більшість?

Мабуть, суперечливим є те, що можна документувати все, включаючи синтаксис геттерів та сеттерів "JavaBean" для полів: люди кажуть, що його непотрібне довге і повторне розбиття DRY (не повторюйте себе) , що конвенція про іменування повинна все пояснювати , і це захаращує код / ​​документацію. Іноді ці аргументи спрацьовують. Але в іншому випадку ви закінчуєте це:

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

То коли я повинен документувати? Чи я документую все, навіть якщо це час від часу захаращує код? Або я нічого не документую, оскільки на моїх очах це "очевидно"?

Документуйте все, що має сенс документувати .

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

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

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

Минулого тижня в The Daily WTF була чудова стаття щодо документації. Я думаю, це все говорить, тому я просто залишу посилання:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

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

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

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

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

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

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

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

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

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

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

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

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

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

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