Как сделать документацию для кода и почему программное обеспечение (часто) плохо документировано?

Есть несколько хороших примеров хорошо документированного кода, такого как Java API. Но большая часть кода в публичных проектах, таких как git и внутренние проекты компаний, плохо документирована и не очень удобна для новичков.

На всех этапах разработки программного обеспечения мне приходилось иметь дело с плохо документированным кодом. Я заметил следующие вещи -

1. Мало или нет комментариев в коде.
2. Имена методов и переменных не описывают сами себя.
3. Существует мало или нет документации о том, как код вписывается в систему или бизнес-процессы.
4. Наем плохих разработчиков или не наставничество хороших. Они не могут написать простой и чистый код. Следовательно, его трудно или невозможно никому, включая разработчика, документировать код.

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

Я узнал, что документации не уделяется того внимания, которого она заслуживает, по следующим причинам:

1. Лень.
2. Разработчики не любят ничего делать, кроме кода.
3. Безопасность работы. (Если никто не может легко понять ваш код, то вы не сможете легко заменить его.)
4. Трудные сроки оставляют мало времени для документирования.

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

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

Есть ли способ покончить с этим безумием или облегчить его? «Документно-ориентированная разработка» возможно?

Как документировать код?

У вас уже есть подсказка: посмотрите, как задокументирован Java API.

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

Почему многие проекты с открытым исходным кодом плохо документированы?

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

Почему многие проекты с закрытым исходным кодом плохо документированы?

Потому что (1) написать хорошую документацию и (2) поддерживать ее стоит огромных денег.

1. Непосредственные затраты (стоимость написания документации) четко видны заинтересованным сторонам: если ваша команда попросит потратить следующие два месяца на документирование проекта, это еще два месяца зарплаты для оплаты.

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

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

Я часто наблюдаю, что:

1. В начале команда готова много документировать.

2. Со временем сжатые сроки и отсутствие интереса усложняют ведение документации.

3. Несколько месяцев спустя новый человек, который присоединяется к проекту, практически не может использовать документацию, потому что она совсем не соответствует реальной системе.

4. Заметив, что руководство обвиняет разработчиков в том, что они не ведут документацию; разработчики просят потратить несколько недель на его обновление.

   • Если руководство предоставляет несколько недель для этого, цикл повторяется.

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

Документация должна быть непрерывным процессом, как и тестирование. Потратьте неделю, просто кодируя несколько тысяч LOC, и возвращаться к тестам и документации очень, очень больно.

Как побудить команду написать документацию?

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

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

• Проводите систематические проверки кода, включая официальные проверки кода, направленные на проверку документации.

• Если некоторые члены команды особенно не относятся к хорошей документации (или к документации вообще), обсудите с ними этот вопрос в частном порядке, чтобы понять, какие препятствия мешают им писать лучшую документацию. Если они обвиняют нехватку времени, вы видите источник проблем.

• Сделайте измеримым присутствие или отсутствие документации на несколько недель или месяцев, но не сосредотачивайтесь на этом. Например, вы можете измерить количество строк комментариев на один LOC, но не делайте это постоянной мерой, иначе разработчики начнут писать длинные, но бессмысленные комментарии, просто чтобы избавиться от низких оценок.

• Используйте геймификацию. Это приходит вместе с предыдущим пунктом.

• Используйте положительное / отрицательное подкрепление .

• (См. Комментарий SJuan76 ) Относитесь к отсутствию комментариев как к ошибкам. Например, в Visual Studio вы можете выбрать опцию для генерации XML-документации. Если вы также проверите, что все предупреждения рассматриваются как ошибки, отсутствие комментария вверху класса или метода остановит компиляцию.

  Что касается трех предыдущих пунктов, этот следует использовать с осторожностью. Некоторое время я использовал его с особенно крутой командой начинающих программистов, и в итоге он получил комментарии, соответствующие StyleCop:

    /// <summary>
    /// Gets or sets the PrimaryHandling.
    /// </summary>
    public Workflow PrimaryHandling { get; set; }

которые были, хм ..., не особенно полезны.

Помните: ничто из автоматизированного не может помочь вам определить плохие комментарии, когда программисты хотят напортачить с вами . Только обзоры кода и другие человеческие задачи помогут.

Есть ли хорошие примеры, когда требуется минимальная документация или нет?

Документация, объясняющая архитектуру и дизайн , не нужна:

• За прототип,

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

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

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

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

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

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

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

ТЛ; др

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