Методология документирования существующей кодовой базы

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

Мой вопрос таков:

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

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

Документирование устаревших кодовых баз

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

Документация в коде

Самое главное - использовать средства документации в выбранной вами среде разработки, что означает pydoc для python, javadoc в java или xml комментарии в C #. Это облегчает написание документации одновременно с написанием кода.

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

Тесты как документация

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

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

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

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

Документация высшего уровня

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

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

Мне очень нравится первое , поскольку из него легко создавать как html-страницы, так и pdf-документы, и оно намного удобнее, чем LaTeX , но все же может включать математические выражения LaTeX, когда они вам нужны.

Каверзный вопрос. По сути, я бы использовал метод «рефакторинга», который я бы назвал «если вы прикоснетесь к коду, задокументируйте его».

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

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

Следует также отметить одну вещь; у вас должна быть хорошая внешняя документация. Вы говорите, что в вашем коде нет ссылок на внешнюю документацию; Я надеюсь, что такая внешняя документация существует. Если нет, я бы на самом деле сделал написание этой внешней документации своим первым приоритетом; что-то на уровне функциональной спецификации, я думаю, абсолютно необходимо для всех крупных программных проектов. Причина в том, что функциональные спецификации или высокоуровневая документация этой формы могут помочь предотвратить «смещение функций» или «отклонение функций» в любом программном обеспечении; и дрейф признаков (в частности) может быть разрушительным для документации, поскольку это может привести к устареванию документации. (Я определяю ползучесть функций как постепенное (и раздражающее) добавление функций к части программного обеспечения; дрейф функцийс другой стороны, это то место, где набор действий, которые выполняет программное обеспечение, медленно меняется с течением времени. Ползучесть функций является ДОПОЛНИТЕЛЬНОЙ, т. Е. Обычно включает увеличение набора функциональных возможностей программного обеспечения; дрейф признаков, с другой стороны, равен нулю; один за другим, определенная часть функциональности пограничного уровня определяется для выполнения чего-то другого, пока программное обеспечение не сделает что-то совершенно иное, чем предполагалось изначально. Особенность дрифта встречается редко, но СРОЧНО для документации.)

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

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

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

Мы использовали XML-документацию в C #, и она предоставила достаточно функций и структур, чтобы упростить документирование. Даже если вы не документируете приложение на C #, шаблон краткой сводки, за которой следовали замечания, был очень полезным.

Я бы задокументировал, как я добавил / изменил код. Кроме этого, я бы также задокументировал публичные API или любые интерфейсы между модулями. Если вы должны были документировать весь код, вы можете не увидеть ROI за потраченное время. Может быть полезно использовать что-то вроде вики для организации внешней документации по мере ее разработки. Самым полезным документом, на который я ссылался, когда начинал свой последний проект, был документ по архитектуре. Он включал информацию об используемых технологиях и обеспечивал общее представление о том, как приложение было наслоено.

Я бы использовал комментарии Doxygen. Doxygen имеет больше форматов вывода, чем большинство других бесплатных форматов, и его легко освоить.

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

Другой распространенный метод - назначить нового разработчика для документирования кода. Затем пусть каждый новый человек пройдет через это, когда они наберут скорость. Имейте в виду, что некоторые разработчики рассматривают это как получение корневого канала - это необходимо только в прямых случаях, LOL.

Прежде чем начать документировать что-либо, разработайте стандарт. Это может быть так же просто, как убедиться, что вы написали несколько строк над заголовком функции или класса в более официальном и подробном виде (например, в javadoc). Прежде чем кто-либо сможет проверить код, его документация должна соответствовать этому стандарту.

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