Скільки документації вистачає?

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

Пападімуліс стверджує, що слід

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

Це хороша настанова, чи я маю створювати конкретні речі?

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

Досконалість є відвідувачем без перекладу, а також плюсом, а також пенсіонером, а також пенсіонером.
Антуан де Сент-Екзюпері

Я певний час думав над цією темою.

Мій висновок такий - справа не в кількості, а в якості та контексті.

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

Аналогічно класифікація для уточнення контексту назви імен (Id on a Patient -> Patient.Id).

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

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

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

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

Шаблони дизайну - це не просто «хороша практика» - це нам слід зрозуміти розробникам. Повідомлення розробника про додавання нового типу до Фабрики краще зрозуміти, ніж додати новий тип до методу (де контекст і послідовність слабкі або відсутні).

Половина боротьби - це знайомство .

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

Щодо коментування, завжди добре вказати на доменну логіку, яка стоїть за міркуванням.

Наприклад, ви працюєте в медичній галузі. У своєму методі ви пишете "IsPatientSecure = true;"

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

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

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

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

Я не знаю хорошого співвідношення.

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

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

Досить змусити вас перестати вдруге здогадуватися про себе.

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

Полоскання-повторюйте, поки це почуття не згасне.

Я виявив, що підхід, орієнтований на ризик, такий, як представлений у книзі Джорджа Фейрбенкса " Just Enough Software Architecture" працює надзвичайно добре, щоб зрозуміти, наскільки достатньо документації. Ви можете прочитати розділ, який представляє цю концепцію (глава 3) на його веб-сайті, але головна ідея:

• Висловіть те, що вас хвилює щодо «розуміння системи» як ризику
• Визначте пріоритетні ризики
• Пом'якшуйте ризики, поки ваша команда не відчує, що ризик проекту був достатньо зменшеним. У цьому випадку ви, ймовірно, будете створювати якусь документацію.

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

Тепер визначте деякі ризики. За допомогою системи, яку ви створили (або будуєте), які речі найбільше хвилюють вашу команду? Сформулюйте їх як заяви про ризик. Мені подобається стиль умови та наслідків SEI, але є й інші. Приклади:

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

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

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

Якнайменше, але стільки, скільки потрібно

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

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

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

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

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

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

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