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

Кто-нибудь когда-нибудь пытался создать полную документацию кода, прежде чем писать код? Я думал об этом раньше, потому что думал, что это поможет написать конкретный интерфейс и позволит убедиться, что ваш первоначальный дизайн не потерпел неудачу, заставив вас задуматься о том, как взаимодействуют классы. Это хорошая идея? Кто-нибудь пробовал это? флигель

Да.

Это заставляет вас задуматься о том, что именно должен делать ваш код . Идея состоит в том, что вы можете начать с любой части кода и точно знать, что нужно сделать для завершения этого модуля.

Также легче исправить что-либо на чертежной доске, чем в 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 . Вот почему:

README не документирует каждую деталь вашего проекта. Вместо этого он обычно содержит следующую информацию:

1. Описание : короткая «коммерческая подача». Скажите читателю, почему они должны продолжать читать.
2. Быстрые примеры : короткие фрагменты кода или скриншоты для поддержки описания.
3. Быстрый старт : как начать работу, инструкции по установке и другие примеры.
4. Дополнительная документация : ссылки на полные документы и дополнительную информацию.
5. Организация проекта : кто авторы, как внести свой вклад, как регистрировать ошибки.
6. Юридические уведомления : лицензия, авторское право и любые другие юридические детали.

Написание «рекламного тона» заранее заставляет меня быть предельно ясным о том, почему этот проект должен существовать и почему разработчики должны его использовать. Сам процесс написания полных предложений для описания проекта часто меняет его к лучшему: вы понимаете его лучше, разрабатываете новые идеи и обнаруживаете потенциальные проблемы. Это также отличный инструмент приоритизации: все, что находится в «поле продаж», обязательно нужно иметь!

«Быстрые примеры» и «краткое руководство» заставляют меня продумать ключевые варианты использования с точки зрения пользователя. Я обнаружил, что выполнение этого перед написанием какого-либо кода - прежде чем увязнуть в деталях реализации и сжатых сроках - приводит к гораздо более чистым API и проектам. Помните: программы должны быть написаны для людей, которые будут читать, и только для машин, которые будут выполняться ( SICP ).

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

Когда у вас есть этот базовый README, у вас есть документ, который будет полезен для обсуждения, анализа дизайна, разделения работы и планирования проекта. Когда вы работаете над проектом, часто проверяйте README, чтобы убедиться, что вы все еще на правильном пути. Кроме того, постепенное обновление README и «дальнейшая документация» по мере того, как вы идете, означает, что вся ваша документация будет сделана, когда код будет готов, что гораздо более приятное занятие, чем спешка с документированием всего в последнюю минуту.

Для получения дополнительной информации, проверьте следующее:

1. Readme Driven Development
2. Самый важный код не код
3. Вы то, что вы документ

Почему бы вам не подумать о том, как взаимодействуют классы? Почему это плохо? Я на самом деле думаю о взаимодействиях, прежде чем я даже знаю, что такое классы. Таким образом, классы идентифицируют себя.

Вы должны иметь представление о том, что вы планируете делать, прежде чем писать код. Вопрос всегда в том, как вы синхронизируете то, что написали, с тем, что написали? Некоторые говорят, что не пытайтесь, другие говорят, что забыли начальные документы и продолжайте комментарии. Конечно, код всегда является каноническим источником. Тогда возникает вопрос, стоит ли усилий документировать, что код делает для тех, кто придет позже или использует код. Любой может понять, что делает функция. Работа писателя состоит в том, чтобы помочь кому-то понять за 5 минут, что каждый может понять за час. Сложите дельты и определите свой путь.