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

35

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

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

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

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

Джордж Стокер
источник
1
+1 Как управлять этим так же важно, как и как это сделать.
1
Большая часть кода, который я видел, не документирована. Я попытался почистить чужие кодовые коды, и меня кричали на это, и это появилось в моем ежегодном обзоре. Если у вас есть все время в мире, или им все равно, как вы проводите свои 50 часов работы, тогда вопрос, безусловно, должен звучать так: «Как мне это сделать?». Тем не менее, вы уверены, что хотите это сделать? Многое зависит от культуры компании, от того, насколько они отчаянно хотят увеличить продажи, насколько хорошо они понимают бизнес программного обеспечения, ... какой язык и инструменты они используют. Для C # есть отличный инструмент под названием StyleCop, а также GhostDoc. Инструменты существуют, но времени мало.
Работа
1
Рассматривали ли вы принять ответ на этот вопрос? Если вы ищете не наши ответы, возможно, вы могли бы обновить свой вопрос. Тогда я с удовольствием обновлю свой ответ, чтобы лучше соответствовать вашему вопросу.
Марк Бут

Ответы:

18

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Марк Бут
источник
4
+1 для бойскаута, но больше, потому что вы единственный человек, который упомянул тесты. Тесты подтверждают ваши предположения о коде, являются языком общения для разработчиков и никогда не нарушают синхронизацию (при условии, что вы не пропустите их).
earcam
16

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

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

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

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

Пол Сонье
источник
Можете ли вы рассказать больше о дрейфе функций? Я понимаю, что это смертельно для документации; поскольку документация и программное обеспечение могут расходиться. Но следует ли избегать дрейфа функций? Положительной стороной является то, что программное обеспечение развивается с изменяющимися требованиями. Мы могли бы сделать наш дизайн с учетом дрейфа функций: предполагается, что архитектура «снизу вверх» приведет к изменчивому программному обеспечению: например, Emacs и TeX имеют архитектуру снизу вверх. Каковы плохие аспекты дрейфа функций для программного обеспечения?
Каспер ван ден Берг
4

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

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

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

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

NigelTufnel
источник
3

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


источник
2

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

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

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

SnoopDougieDoug
источник
1

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

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


источник