Как документировать код?
У вас уже есть подсказка: посмотрите, как задокументирован Java API.
В более общем смысле, не существует уникального набора правил, применимых к каждому проекту. Когда я работаю над важными для бизнеса крупномасштабными проектами, документация не имеет ничего общего с той, которую я написал бы для небольшой библиотеки с открытым исходным кодом, что, в свою очередь, не имеет ничего общего с документацией моего среднего личного проекта ,
Почему многие проекты с открытым исходным кодом плохо документированы?
Потому что большинство проектов с открытым исходным кодом сделаны людьми, которые участвуют в этих проектах, потому что это весело. Большинство программистов и разработчиков считают, что написание документации недостаточно увлекательно, чтобы заниматься бесплатно.
Почему многие проекты с закрытым исходным кодом плохо документированы?
Потому что (1) написать хорошую документацию и (2) поддерживать ее стоит огромных денег.
Непосредственные затраты (стоимость написания документации) четко видны заинтересованным сторонам: если ваша команда попросит потратить следующие два месяца на документирование проекта, это еще два месяца зарплаты для оплаты.
Долгосрочные затраты (затраты на ведение документации) становятся довольно заметными для менеджеров, и зачастую являются первой целью, когда они должны снизить стоимость или сократить задержки. Это вызывает дополнительную проблему устаревшей документации, которая быстро становится бесполезной и чрезвычайно дорогой для обновления.
С другой стороны, трудно измерить долгосрочную экономию (экономию от того, что не нужно тратить несколько дней на изучение унаследованного кода только для того, чтобы понять основную вещь, которая должна была быть задокументирована много лет назад), что подтверждает мнение некоторых руководителей что написание и ведение документации - пустая трата времени.
Я часто наблюдаю, что:
В начале команда готова много документировать.
Со временем сжатые сроки и отсутствие интереса усложняют ведение документации.
Несколько месяцев спустя новый человек, который присоединяется к проекту, практически не может использовать документацию, потому что она совсем не соответствует реальной системе.
Заметив, что руководство обвиняет разработчиков в том, что они не ведут документацию; разработчики просят потратить несколько недель на его обновление.
Если руководство предоставляет несколько недель для этого, цикл повторяется.
Если руководство отказывается, основываясь на предыдущем опыте, это только усугубляет плохой опыт, поскольку у продукта нет документации, но несколько месяцев было потрачено на его написание и обслуживание.
Документация должна быть непрерывным процессом, как и тестирование. Потратьте неделю, просто кодируя несколько тысяч LOC, и возвращаться к тестам и документации очень, очень больно.
Как побудить команду написать документацию?
Подобно способам побуждать людей писать чистый код, проводить регулярный рефакторинг, использовать шаблоны проектирования или добавлять достаточное количество модульных тестов.
Подавать пример. Если вы напишите хорошую документацию, ваши пары тоже могут начать это делать.
Проводите систематические проверки кода, включая официальные проверки кода, направленные на проверку документации.
Если некоторые члены команды особенно не относятся к хорошей документации (или к документации вообще), обсудите с ними этот вопрос в частном порядке, чтобы понять, какие препятствия мешают им писать лучшую документацию. Если они обвиняют нехватку времени, вы видите источник проблем.
Сделайте измеримым присутствие или отсутствие документации на несколько недель или месяцев, но не сосредотачивайтесь на этом. Например, вы можете измерить количество строк комментариев на один LOC, но не делайте это постоянной мерой, иначе разработчики начнут писать длинные, но бессмысленные комментарии, просто чтобы избавиться от низких оценок.
Используйте геймификацию. Это приходит вместе с предыдущим пунктом.
Используйте положительное / отрицательное подкрепление .
(См. Комментарий SJuan76 ) Относитесь к отсутствию комментариев как к ошибкам. Например, в Visual Studio вы можете выбрать опцию для генерации XML-документации. Если вы также проверите, что все предупреждения рассматриваются как ошибки, отсутствие комментария вверху класса или метода остановит компиляцию.
Что касается трех предыдущих пунктов, этот следует использовать с осторожностью. Некоторое время я использовал его с особенно крутой командой начинающих программистов, и в итоге он получил комментарии, соответствующие StyleCop:
/// <summary>
/// Gets or sets the PrimaryHandling.
/// </summary>
public Workflow PrimaryHandling { get; set; }
которые были, хм ..., не особенно полезны.
Помните: ничто из автоматизированного не может помочь вам определить плохие комментарии, когда программисты хотят напортачить с вами . Только обзоры кода и другие человеческие задачи помогут.
Есть ли хорошие примеры, когда требуется минимальная документация или нет?
Документация, объясняющая архитектуру и дизайн , не нужна:
За прототип,
Для личного проекта, написанного за несколько часов, чтобы выполнить задачу, будучи уверенным, что этот проект больше не будет обслуживаться,
Для любого проекта, где очевидно, учитывая его небольшой размер в сочетании с особенно чистым кодом, вы потратите больше времени на написание документации, чем все будущие сопровождающие, исследующие код.
Документация в коде (комментарии к коду) не требуется, по мнению некоторых разработчиков, когда код самодокументируется. Для них наличие комментариев, за исключением редких случаев, не является хорошим признаком, но признаком того, что код не был подвергнут рефакторингу, чтобы его можно было очистить без комментариев.
Я чувствую, что у нас должен быть обзор документации после завершения проекта.
Если ваш проект поставляется по крайней мере один раз в неделю, это путь. Если ваш проект не является гибким и выполняется с интервалом в шесть месяцев, проводите более регулярные проверки.