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

11

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

флигель
источник
2
Да. Это хорошая идея. Люди делают это все время. Что еще ты хочешь знать?
S.Lott
9
Это субъективный вопрос. Кто-то делал это, по крайней мере, иногда, поэтому ответ должен быть положительным. Лично я предпочитаю просто заскочить и сделать прототип первым, так как я неизбежно заново открою лучший дизайн примерно в 5 раз. Решая что-то сложное, я сначала что-то царапаю на листе бумаги. Если это тривиально, то я, как правило, прыгаю прямо внутрь. StyleCop помогает мне заполнить пробелы позже.
Работа
2
Это отличная идея, в противном случае вы получите недокументированные функции.
Chrisw
8
@ S.Lott: простой факт, что он задает вопрос, подразумевает, что он ищет какую-то дополнительную информацию, так как я уверен, что вы знали. Но, похоже, вы предпочитаете делать глупые комментарии о недостатках других людей.
Кеннет
2
Было бы еще лучше, если бы вы написали приемочные тесты, а затем использовали TDD для выполнения этих приемочных тестов;).
Мартин Блор,

Ответы:

5

Да.

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

Также легче исправить что-либо на чертежной доске, чем в IDE.

Maxpm
источник
12
Проще исправить, да. Легче заметить, редко. Проекты почти всегда выглядят хорошо, пока вы не попытаетесь их реализовать.
CaffGeek
@ Чад Это правда. Я отредактировал свой ответ, чтобы отразить это.
Макс.
4
Я не согласен. Создание полной документации сначала намного хуже, чем просто достаточное количество документации, чтобы знать, куда идти дальше. Изменение происходит. Нет никакого способа узнать, движетесь ли вы в правильном направлении, и к тому времени, как вы это выясните, вы уже далеко позади. Пойдите с тем, что работает, улучшите и исправьте это, поскольку вы идете, позвольте коду быть самой современной документацией.
Захари Скотт
4
Конечно, как только вы измените свой код, чтобы исправить ошибку или выполнить новое требование, ваша документация устареет. Документация как исполняемые тесты - путь!
Johnsyweb
Заранее нарисуйте (нарисуйте / обрисуйте) идеи, но не создавайте документацию. Если вы не предпочитаете тратить много усилий, потому что вы отбрасываете много первоначальных усилий, поскольку дизайн применяется на практике. Кроме того, только публичные или внутренние классы / методы должны быть полностью документированы (включая полное описание, а также параметры). Частные локальные вещи должны иметь однострочники, которые описывают то, что они делают для дальнейшего использования, но все остальное - пустая трата времени, потому что в любом случае они неизбежно будут пропущены на этапе создания документации.
Эван Плейс
10

Есть два способа думать об этом:

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

2) Документация как исполняемые тесты. Существует школа мысли, которая утверждает, что исполняемые модульные тесты - лучшая документация. Эта школа мысли также поддерживает такую ​​документацию, прежде чем писать код (TDD). В то же время вы не пишете все тесты для всей системы с самого начала. Сначала вы разбиваете его по сценариям использования, затем выполняете тесты и код для каждого варианта использования.

Юрий Зубарев
источник
2
+1 за TDD. Абсолютно лучший вариант, чем документирование, тогда придется менять значительные объемы документации, если код меняется.
Этель Эванс
Также +1 за документацию в виде TDD.
sevenseacat
Вы МОЖЕТЕ иметь полную документацию по продукту до его появления. Я сделал это, я работал в проектах, где это было требованием. У вас не будет скриншотов, но вы можете иметь все остальное (включая диаграммы Visio, отображающие расположение элементов на экране).
jwenting
@jwenting У меня тоже, и это была коллекция диаграмм, а также более 200 страниц текстовых документов. Мало того, что это была пустая трата времени, но потребовалось 2 месяца, чтобы произвести и значительное количество времени наших постоянных менеджеров, чтобы постоянно обновлять, поскольку дизайн развился в конечный продукт. Возможно, с графическими макетами, использующими Balsalmiq, все было бы намного быстрее. В следующий раз, когда я буду работать над проектом, где это требование, я собираюсь подчеркнуть, что другой человек должен быть назначен для управления им на полную ставку, потому что это столько усилий, сколько требуется для поддержания.
Эван Плейс
+1 TDD для базовых доказательств отдельных компонентов и диаграмм для общих предположений проекта (акцент на предположении, потому что фактический проект должен быть написан как лучшее практическое приложение, а не реализация схемы 1-1, они называются предположениями по причине ). Полная программная документация по всем открытым / внутренним классам / методам / свойствам поступает в последнюю очередь через генератор документации (все свойства / возвраты / замечания должны быть заполнены в первую очередь), а все личные / локальные вещи получают однострочно, чтобы описать, что они делают для дальнейшего использования (private / local игнорируется генератором).
Эван Плейс
7

Начало документации - классическая модель водопада, в которой есть все подводные камни, связанные с этой моделью. В целом, чем больше вы документируете, тем больше вы должны обновлять при изменении требований. Одним из преимуществ начала работы с пользовательской документацией является то, что вы можете получить обратную связь (и, следовательно, изменения) раньше. Но опыт показывает, что большинство людей плохо умеют сопоставлять документацию с действиями. Таким образом, вместо этого мы используем прототипы, которые позволяют людям реально использовать программное обеспечение и дают обратную связь таким образом.

Одним из вариантов «сначала документации» является грамотное программирование . Начните с написания описания того, что программа будет делать с точки зрения программистов. Продолжайте настраивать это, пока это не скомпилируется. Вуаля, грамотная программа.


источник
Точно! Изменение происходит. Документация гниет. Код является наиболее верной формой документации.
Захари Скотт
3

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

РЕДАКТИРОВАТЬ: Хотя некоторые документы должны быть сделаны, как вы долго. Это облегчает создание полной документации позже.

Кеннет
источник
3

Джошуа Блох обсуждает этот момент в своем интервью для книги «Кодеры на работе».

Вопреки более ортодоксальным и академическим взглядам, он советует что-то под настроение ваших мыслей (может быть, вы читали это там сами?): Что перед написанием документации вы должны понять, чего вы хотите от системы, и получить более «реальный» чувство Для этого он разработал бы часть интерфейсов и некоторый клиентский код, который их использует.

Самое главное, чтобы знать, что вы пытаетесь построить: какую проблему вы пытаетесь решить. Важность анализа требований невозможно переоценить. Есть люди, которые думают: «О, да, анализ требований; Вы идете к своему клиенту, вы говорите: «Что вам нужно?» Он говорит тебе, и ты готов.

Нет ничего более далекого от правды. Это не только переговоры, но и процесс понимания. Многие клиенты не скажут вам проблемы; они скажут вам решение. Например, клиент может сказать: «Мне нужно, чтобы вы добавили поддержку следующих 17 атрибутов в эту систему. Тогда вы должны спросить: «Почему? Что вы собираетесь делать с системой? Как вы ожидаете, что это будет развиваться? »И так далее. Вы ходите взад и вперед, пока не поймете, для чего действительно нужно программное обеспечение всем клиенту. Это случаи использования.

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

Худшее, что вы можете сделать - и я видел, как это произошло, - это привести кучку умных парней в комнату для работы на шесть месяцев и написать спецификацию системы на 247 страниц, прежде чем они действительно поймут, что это такое. пытаюсь построить. Потому что через шесть месяцев у них будет очень четко определенная система, которая вполне может оказаться бесполезной. И часто они говорят: «Мы вложили так много в спецификацию, что мы должны ее построить». Таким образом, они строят бесполезную систему, и она никогда не используется. И это ужасно. Если у вас нет вариантов использования, вы создаете эту вещь, а затем пытаетесь сделать что-то очень простое и понимаете, что: «О, черт возьми, делать что-то очень простое, например, взять документ XML и распечатать его, требует страниц на страницах шаблонов». код." И это ужасная вещь.

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

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

ДПМ
источник
Это хороший совет, но хорошая документация включает использование API.
Фрэнк Хайлеман
Для справки, хотя я ценю редактирование, я думаю, что эта цитата, возможно, была не той, о которой я думал. Это кажется касательно и более высоким уровнем или связанным с фазой требований. Я думаю, что он сказал, что прежде чем писать документацию, он должен начать писать код, писать код клиента, который будет использовать интерфейс, чтобы иметь общее представление о правильном интерфейсе, и что (это, на мой взгляд, противоречивая интуитивная часть) должно произойти первым, прежде чем писать какой-либо документ дизайна низкого уровня вообще. Конечно, я виноват в том, что не нашел цитату, когда написал этот ответ.
DPM
1

Некоторые люди даже идут дальше и заявляют, что компания должна полностью работать в обратном направлении, поэтому

  1. Написать пресс-релиз
  2. Написать FAQ
  3. Определите опыт клиента
  4. Написать руководство пользователя
  5. Начать программирование

См. Http://www.allthingsdistributed.com/2006/11/working_backwards.html.

asmaier
источник
1

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

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

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

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

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

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

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

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

  1. Readme Driven Development
  2. Самый важный код не код
  3. Вы то, что вы документ
Евгений Брикман
источник
0

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

Замочить
источник
0

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

SnoopDougieDoug
источник