Кто-нибудь когда-нибудь пытался создать полную документацию кода, прежде чем писать код? Я думал об этом раньше, потому что думал, что это поможет написать конкретный интерфейс и позволит убедиться, что ваш первоначальный дизайн не потерпел неудачу, заставив вас задуматься о том, как взаимодействуют классы. Это хорошая идея? Кто-нибудь пробовал это? флигель
documentation
флигель
источник
источник
Ответы:
Да.
Это заставляет вас задуматься о том, что именно должен делать ваш код . Идея состоит в том, что вы можете начать с любой части кода и точно знать, что нужно сделать для завершения этого модуля.
Также легче исправить что-либо на чертежной доске, чем в IDE.
источник
Есть два способа думать об этом:
1) Документация, как в документах Word, Wiki и т. Д. По определению вы не можете иметь полную документацию по коду, потому что у вас нет кода для документирования. Вы можете сначала попытаться задокументировать дизайн, допущения, интерфейсы и контракты на высоком уровне.
2) Документация как исполняемые тесты. Существует школа мысли, которая утверждает, что исполняемые модульные тесты - лучшая документация. Эта школа мысли также поддерживает такую документацию, прежде чем писать код (TDD). В то же время вы не пишете все тесты для всей системы с самого начала. Сначала вы разбиваете его по сценариям использования, затем выполняете тесты и код для каждого варианта использования.
источник
Начало документации - классическая модель водопада, в которой есть все подводные камни, связанные с этой моделью. В целом, чем больше вы документируете, тем больше вы должны обновлять при изменении требований. Одним из преимуществ начала работы с пользовательской документацией является то, что вы можете получить обратную связь (и, следовательно, изменения) раньше. Но опыт показывает, что большинство людей плохо умеют сопоставлять документацию с действиями. Таким образом, вместо этого мы используем прототипы, которые позволяют людям реально использовать программное обеспечение и дают обратную связь таким образом.
Одним из вариантов «сначала документации» является грамотное программирование . Начните с написания описания того, что программа будет делать с точки зрения программистов. Продолжайте настраивать это, пока это не скомпилируется. Вуаля, грамотная программа.
источник
Я лично считаю, что лучше использовать диаграммы (такие как UML) для простого моделирования, чтобы показать ход вещей. Это гораздо быстрее, чем документировать все на словах, и, если все сделано правильно, может быть не менее описательным. Я бы не решался делать полную документацию, потому что лично у меня никогда не было проекта, над которым я работал, который не изменился в процессе его программирования.
РЕДАКТИРОВАТЬ: Хотя некоторые документы должны быть сделаны, как вы долго. Это облегчает создание полной документации позже.
источник
Джошуа Блох обсуждает этот момент в своем интервью для книги «Кодеры на работе».
Вопреки более ортодоксальным и академическим взглядам, он советует что-то под настроение ваших мыслей (может быть, вы читали это там сами?): Что перед написанием документации вы должны понять, чего вы хотите от системы, и получить более «реальный» чувство Для этого он разработал бы часть интерфейсов и некоторый клиентский код, который их использует.
Если вы уже размышляете в этом направлении, было бы хорошо, если бы вы взялись за книгу и прочитали все интервью. Как я уже сказал, он всегда очень поучительный.
источник
Некоторые люди даже идут дальше и заявляют, что компания должна полностью работать в обратном направлении, поэтому
См. Http://www.allthingsdistributed.com/2006/11/working_backwards.html.
источник
Написание полной документации кода сначала, вероятно, излишне и чем-то напоминает методологию водопада. Тем не менее, я обнаружил, что более прагматичный подход - сначала написать README . Вот почему:
README не документирует каждую деталь вашего проекта. Вместо этого он обычно содержит следующую информацию:
Написание «рекламного тона» заранее заставляет меня быть предельно ясным о том, почему этот проект должен существовать и почему разработчики должны его использовать. Сам процесс написания полных предложений для описания проекта часто меняет его к лучшему: вы понимаете его лучше, разрабатываете новые идеи и обнаруживаете потенциальные проблемы. Это также отличный инструмент приоритизации: все, что находится в «поле продаж», обязательно нужно иметь!
«Быстрые примеры» и «краткое руководство» заставляют меня продумать ключевые варианты использования с точки зрения пользователя. Я обнаружил, что выполнение этого перед написанием какого-либо кода - прежде чем увязнуть в деталях реализации и сжатых сроках - приводит к гораздо более чистым API и проектам. Помните: программы должны быть написаны для людей, которые будут читать, и только для машин, которые будут выполняться ( SICP ).
В «дальнейшей документации» я создаю план частей, которые будут нуждаться в подробной документации, которая будет сделана позже. «Организация проекта» позволяет мне выяснить, кто будет работать над проектом и практикой кодирования. «Юридические уведомления» ... ну, может, и их тоже убрать.
Когда у вас есть этот базовый README, у вас есть документ, который будет полезен для обсуждения, анализа дизайна, разделения работы и планирования проекта. Когда вы работаете над проектом, часто проверяйте README, чтобы убедиться, что вы все еще на правильном пути. Кроме того, постепенное обновление README и «дальнейшая документация» по мере того, как вы идете, означает, что вся ваша документация будет сделана, когда код будет готов, что гораздо более приятное занятие, чем спешка с документированием всего в последнюю минуту.
Для получения дополнительной информации, проверьте следующее:
источник
Почему бы вам не подумать о том, как взаимодействуют классы? Почему это плохо? Я на самом деле думаю о взаимодействиях, прежде чем я даже знаю, что такое классы. Таким образом, классы идентифицируют себя.
источник
Вы должны иметь представление о том, что вы планируете делать, прежде чем писать код. Вопрос всегда в том, как вы синхронизируете то, что написали, с тем, что написали? Некоторые говорят, что не пытайтесь, другие говорят, что забыли начальные документы и продолжайте комментарии. Конечно, код всегда является каноническим источником. Тогда возникает вопрос, стоит ли усилий документировать, что код делает для тех, кто придет позже или использует код. Любой может понять, что делает функция. Работа писателя состоит в том, чтобы помочь кому-то понять за 5 минут, что каждый может понять за час. Сложите дельты и определите свой путь.
источник