Документація коду спочатку? [зачинено]

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

Так.

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

Також простіше виправити щось на дошці для малювання, ніж на IDE.

Існує два способи мислення про це:

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

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

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

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

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

РЕДАКТУВАННЯ: Хоча деяку документацію слід робити довгий час. Це полегшує зробити повну документацію пізніше.

Джошуа Блох обговорює саме цей момент у своєму інтерв'ю до книги "Кодери на роботі".

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

Найголовніше - знати, що ви намагаєтеся побудувати: яку проблему ви намагаєтеся вирішити. Важливість аналізу вимог не можна завищувати. Є люди, які думають: "О так, аналіз вимог; ви йдете до свого замовника, ви говорите: "Що вам потрібно?" Він тобі каже, і ти закінчив ».

Ніщо не могло бути далі від істини. Це не лише переговори, але це процес розуміння. Багато клієнтів не скажуть вам проблеми; вони підкажуть вам рішення. Клієнт може сказати, наприклад, «Мені потрібно, щоб ти додавав підтримку наступних 17 атрибутів до цієї системи. Тоді ви повинні запитати: "Чому? Що ти збираєшся робити із системою? Як ти очікуєш, що він розвиватиметься? '»І так далі. Ви їдете туди-сюди, поки не з’ясуєте, що саме клієнту дійсно потрібно програмне забезпечення. Це випадки використання.

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

Найгірше, що ви можете зробити - і я бачив, як це відбувається - ви забираєте купу розумних хлопців в кімнату, щоб пропрацювати півроку і написати специфікацію системи на 247 сторінках, перш ніж вони дійсно зрозуміють, що це таке намагаються будувати. Тому що через шість місяців у них з'явиться дуже точно визначена система, яка може виявитися марною. І часто вони кажуть: "Ми вклали стільки коштів у специфікацію, що нам доведеться її будувати". Тож вони будують марну систему, і вона ніколи не звикає. І це жахливо. Якщо у вас немає випадків використання, ви будуєте річ, а потім намагаєтесь зробити щось дуже просте, і розумієте, що: «О, мій боже, робиш щось дуже просте, як взяти XML-документ і роздрукувати його, потрібні сторінки на сторінках котла код ». І це жахливо.

- Джошуа Блох, з інтерв'ю в " Кодери на роботі: роздуми про майстерність програмування " Пітера Сейбела

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

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

1. Напишіть прес-реліз
2. Напишіть FAQ
3. Визначте досвід клієнта
4. Напишіть Посібник користувача
5. Почніть програмування

Див. Http://www.allthingsdistributed.com/2006/11/working_backwards.html

Написання повної документації з кодом спочатку, ймовірно, є надмірним і дещо нагадує методологію водоспаду. Однак я виявив, що більш прагматичним підходом є спочатку ПРОЧИТАННЯ . Ось чому:

README не документує кожної деталі вашого проекту. Натомість він, як правило, містить таку інформацію:

1. Опис : короткий "крок продажу". Розкажіть читачеві, чому вони повинні продовжувати читати.
2. Короткі приклади : короткі фрагменти коду або скріншоти для підтримки опису.
3. Швидкий початок : як рухатись, встановлювати інструкції та інші приклади.
4. Подальша документація : посилання на повні документи та більше інформації.
5. Організація проекту : хто є авторами, як зробити внесок, як подавати помилки.
6. Юридичні повідомлення : ліцензія, авторські права та будь-які інші юридичні дані.

Написання "кроку продажу" на передній частині змушує мене бути чітко зрозумілим, чому цей проект повинен існувати і чому розробники повинні його використовувати. Сам акт написання повних пропозицій для опису проекту часто змінює його на краще: ви краще розумієте його, розробляєте нові ідеї та розкриєте потенційні проблеми. Це також чудовий інструмент визначення пріоритетності: все, що є в "кроку продажу", є обов'язковим!

"Швидкі приклади" та "посібник із швидкого запуску" змушують мене продумати ключові випадки використання з точки зору користувача. Я виявив, що це робити перед написанням будь-якого коду - перед тим, як потрапити в деталі щодо впровадження та строгі строки - призводить до набагато більш чітких API та дизайнів. Пам'ятайте: програми повинні бути написані для того, щоб люди читали, і лише випадково для машин, які виконували ( SICP ).

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

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

Для отримання додаткової інформації перегляньте наступне:

1. Readme Driven Development
2. Найважливіший код - це не код
3. Ви - це те, що ви документуєте

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

Ви повинні мати деяке уявлення про те, що плануєте зробити, перш ніж писати код. Питання завжди полягає в тому, як зберегти те, що ви кодували, синхронізовано з тим, що ви написали? Одні кажуть, що не намагайтеся, інші кажуть забути початкові документи та продовжувати коментарі. Звичайно, код завжди є канонічним джерелом. Тоді стає питання, чи варто докладати зусиль, щоб документувати, що код робить для тих, хто приходить пізніше або використовує код. Будь-хто може зрозуміти, що робить функція. Завдання письменника - допомогти комусь зрозуміти за 5 хвилин, що кожен може зрозуміти за годину. Складіть дельти і визначте свій шлях.