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

Сколько технической (для будущих разработчиков) документации достаточно ? Есть ли подходящее соотношение между часовым кодированием и документированием часов?

Пападимулис утверждает, что вы должны

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

Это хорошее руководство, или есть конкретные вещи, которые я должен создать?

Как насчет тестирования удобства использования в коридоре? Покажите код и документацию разработчику, незнакомому с проектом. Когда вы можете сделать это без непреодолимого желания что-то объяснить, наблюдая за тем, как они просматривают код, у вас будет достаточно.

Безупречность - это непременное преимущество и превосходство, а главное - выход на пенсию.
Антуан де Сент-Экзюпери

Я долго думал об этой теме.

Мой вывод - дело не в количестве, а в качестве и контексте.

Например, правильная структура проекта превосходит комментарии, объясняющие, где находятся файлы (реализация или намерение)

Точно так же классификация для уточнения именования контекста бьет (Идентификатор пациента -> Идентификатор пациента).

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

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

Иногда мы забываем, кто главный - если код изменяется, логика или логика домена не должны изменяться, но если логика или логика домена меняется, код определенно изменится.

Согласованность также очень важна - соглашение само по себе бесполезно, если оно не соответствует.

Шаблоны проектирования - это не просто «хорошая практика», это то, что нам, разработчикам, следует понимать. Говорить разработчику о добавлении нового типа в Factory лучше, чем добавлять новый тип в метод (когда контекст и согласованность слабы или отсутствуют).

Половина борьбы - это знакомство .

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

С точки зрения комментирования всегда хорошо указывать на доменную логику, лежащую в основе рассуждений.

Например, вы работаете в медицинской промышленности. В вашем методе вы пишете "IsPatientSecure = true;"

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

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

Возможно, этот пост кажется в лучшем случае философским, но помните, что вы пишете «рассуждения» или «логики», а не код.

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

Я не знаю хорошего соотношения.

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

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

Достаточно, чтобы вы перестали вторую догадываться.

Если в какой-то момент во время вашей работы вы скажете: «Хм, может быть, я должен это задокументировать», продолжайте и сделайте это. Затем, если вы написали какую-то документацию и вам нравится «возможно, мне следует объяснить это подробнее», продолжайте и сделайте это.

Промыть-повторить, пока это чувство не исчезнет.

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

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

Чтобы помочь откалибровать проблемы, чтобы вы могли расставить приоритеты для рисков, я нашел полезным определить пару целей, известных как « Порог успеха» , то есть минимальный набор целей, которые, по мнению вашей команды, должен достичь «успешный» проект. С точки зрения документации, пример ToS может быть чем-то вроде: «Разработчик должен иметь возможность создать простой плагин в течение 4 часов после первого запуска фреймворка».

Теперь определите некоторые риски. С системой, которую вы создали (или строите), что больше всего беспокоит вашу команду? Фраза это как заявления о риске. Мне нравится стиль условий-следствий SEI, но есть и другие. Примеры:

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

Теперь, как команда, приоритизируйте риски. Мульти-голосование работает очень хорошо.

Смягчите риски с высоким приоритетом и повторяйте, начиная с идентификации, до тех пор, пока риск неудачи вашего проекта (определяемый порогом успеха) не окажется в допустимых пределах. Как правило, это будет означать, что у вас есть некоторые риски, которые, по мнению команды, не представляют большой проблемы. Имейте в виду, что вы, вероятно, не захотите смягчить все риски. Примером стратегии смягчения для последнего риска может быть создание учебника.

Как можно меньше, но столько, сколько необходимо

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

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

«Тест прихожей» от JohnFx - это звук. Но верь себе; Вы разработали код, и поэтому вы, люди, должны понимать элементы, которые требуют дополнительного внимания, и элементы, которые будут очевидны для всех. Подумайте о трудностях, с которыми вы столкнулись при разработке кода, и вы, скорее всего, поймете, что увидит другой разработчик, когда он посмотрит на ваш код.

Забудьте о любых отношениях между затраченными усилиями на кодирование и затраченными усилиями на документирование.

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

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

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