Есть ли логическая причина для автоматической генерации документации кода? [закрыто]

Автоматическое создание документации может быть выполнено с помощью различных инструментов, причем GhostDoc является одним из наиболее заметных. Однако по определению все, что он генерирует, является излишним. Он рассматривает имена методов, классов и т. Д. И выводит английский язык, который может объяснить их более подробно. В лучшем случае он делает то, что читатель уже мог сделать в своей голове (примеры взяты отсюда ):

/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...

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

/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...

Кажется, что отношение к GhostDoc таково: «лучше иметь какую-то формальную документацию XML», но когда эта документация на 100% избыточна, почему? Разве это не просто тратить кучу места в лучшем случае?

На моем рабочем месте мы должны документировать все, и почти всегда с автоматически сгенерированными документами GhostDoc. Делаете ли вы это, и есть ли рациональные причины не оставлять код недокументированным, если вы не собираетесь сами писать документацию?

[...] документируйте все, и почти всегда с автоматически сгенерированными документами GhostDoc. Делаете ли вы это, и есть ли рациональные причины не оставлять код недокументированным, если вы не собираетесь сами писать документацию?

Нет. Документация, сгенерированная GhostDoc, является шаблонной (аналогично тому, как создание нового класса OO в IDE создает шаблон для класса с конструктором или чем-то еще). Полезная часть документации - это то, что последует после добавления шаблона.

Хотя вы должны документировать все на своем рабочем месте, кажется, ваши коллеги нашли идеальный способ обойти это: просто притворяться.

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

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

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

Есть ли логическая причина для автоматической генерации документации кода?

С чьей точки зрения?

Если бы я руководил компанией или группой разработчиков, то нет веской причины. Я стойко в "комментариях должен объяснить, почему " лагерь. Заставлять людей комментировать классы / функции / свойства хуже, чем бесполезных, так как они устаревают, вводят читателя в заблуждение, их используют в качестве предлога, чтобы не делать читаемый код, и так далее. Эти комментарии тратят время как на их написание, на чтение кода, так и на ошибки, вызванные ими. Некоторые утверждают, что документы API в стиле JavaDoc являются причиной для комментирования, но даже при таком аргументе небольшая часть вашего кода должна быть частью общедоступного API, а JavaDoc не является заменой для реальных документов API.

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

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

РЕДАКТИРОВАТЬ : я неправильно понял оригинальный вопрос; хотя я думаю, что создание документации (то есть не кодовых документов ) может быть чрезвычайно полезным (см. оригинальный ответ относительно Doxygen ниже), автоматическое создание комментариев (что на самом деле делает GhostDoc) звучит для меня безумно. Я не могу понять, почему кто-то ожидал, что программа сможет читать некомментированный исходный код и писать комментарии, которые действительно его прояснят.

Для меня вполне возможно, что чрезвычайно «умная» утилита генерации комментариев может быть запрограммирована на распознавание определенных шаблонов и генерацию комментариев в стиле «как»; например, он мог бы распознать алгоритм вычисления дисперсии Кнута и предоставить комментарий, объясняющий, как он работает и почему наивный алгоритм не подходит. Возможно, такую ​​утилиту можно даже запрограммировать на распознавание канонических объектно-ориентированных шаблонов проектирования (например, Abstract Factory) и вставлять комментарии, указывающие, какой шаблон используется и какие классы играют и какие роли.

Но, на мой взгляд, самые полезные комментарии не объясняют, «как» что-то работает, так как сам код должен это показывать, а « почему » комментируют, объясняя, «почему» конкретная вещь выполняется. Как отметил Дэвид Хаммен в комментариях ниже, чтобы генерировать комментарии «почему», утилита должна «читать мысли программиста». Очевидно, это невозможно.

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

Оригинальный ответ: почему автоматическое извлечение и форматирование документации - это хорошая идея

Моя команда разработчиков использует Doxygen. Основная причина этого заключается в том, что нам нужна документация функций / поведения / и т. Д., Не относящихся к исходному коду (т. Е. Читаемых непрограммистами), но мы считаем, что лучше интегрировать это в сам исходный код, чем сохранить его как второй документ . Это помогает нам поддерживать синхронизацию документации с исходным кодом (хотя, конечно, это невозможно обеспечить полностью, а тем более автоматизировать) и минимизировать накладные расходы при написании документации (поскольку документация для фрагмента кода может быть легко включена в файл, содержащий сам код).

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

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

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

• Наш продукт не просто программное обеспечение; Это сложный инструмент, который объединяет многие аппаратные компоненты, в том числе некоторые причудливые лазеры и флюиды. Нам нужны инженеры без большого опыта работы с программным обеспечением, чтобы хорошо понимать , как ведут себя внутренние компоненты нашего кода, и сказать им, что они «читают исходный код», этого не удастся.
• Мы должны соблюдать довольно много правил качества, некоторые из которых внутренне предписаны компанией, а другие - юридически уполномоченными федеральным правительством. Хотя процесс обеспечения качества (или, по крайней мере, может быть) чрезвычайно ценен и полезен, он включает в себя немалые накладные расходы, частью которых является обязанность команды разработчиков программного обеспечения предоставлять такого рода подробную документацию по программному обеспечению. Опять же, интеграция этой документации с самим кодом минимизирует накладные расходы и помогает нам поддерживать документацию в актуальном состоянии.

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

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

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

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

В этой форме это хуже, чем бесполезно, но только потому, что оно опирается только на публичную подпись (которая, в случае Javadoc, в любом случае видна всем, кто читает документ API).

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

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

Исходя из этого опыта, ответ на вопрос: да, но нам нужны гораздо более умные инструменты.

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

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

Я не знаю о других средах, но когда дело доходит до больших (часто с открытым исходным кодом) проектов PHP, которые написали другие люди, phpXRef является абсолютным спасением жизни (особенно, если документ размещен в Интернете, и Google может его проиндексировать).

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

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

Кроме того, моя предпочтительная IDE автоматически сгенерирует блок комментариев (если я наберу / **), который выполняет для меня примерно 75% комментариев. Удивительно, сколько глупостей я не мог совершить за свою жизнь программиста только потому, что мне пришлось объяснять другим людям (и будущему мне), что я делаю. Когда мой комментарий к генератору документов больше, чем метод, это обычно означает, что мне не хватило кофе и, возможно, хотелось бы подумать немного сложнее.

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

Я не могу не подчеркнуть, насколько полезно указывать ожидаемые типы ввода в сложных (и часто плохо именуемых) проектах PHP и порядок аргументов в менее часто используемых методах. Даже с моим собственным кодом я не всегда могу вспомнить, какие аргументы я указывал для чего-то, чего я не коснулся в эпоху.

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

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

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

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

Итак, причины включают в себя:

• Экономя последним разработчикам кучу времени,
• Отслеживание того, где функции вызываются (и определяются),
• Обнаружение глупого кодирования,
• Нахождение (как указал другой), когда чего-то явно не хватает,
• Упрощение рефакторинга (никогда не очень весело)
• (Во многих случаях) получить представление о том, что разработчик пытался сделать (при условии, что он или она оставили некоторые заметки).
• Если проект достаточно сложный, чтобы иметь несколько лицензий (неинтересно), я могу быстро увидеть, какие лицензии применимы к любому данному разделу. Правда, это побочный бонус.
• Получить представление о том, с кем поговорить о файле проекта.
• Автоматические списки задач

Кроме того, не стоит недооценивать ценность того, чтобы держать боссов с острыми волосами счастливыми одним нажатием кнопки.

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

Часто полезно использовать генераторы документации для создания шаблонных или «независимых» комментариев, которые затем впоследствии пересматриваются фактическими разработчиками. Я часто использую функцию auto-JavaDoc в Eclipse для генерации комментария к заголовку с уже введенными типами параметров и возвращаемыми значениями, а затем просто добавляю «мясо» документации.

В качестве разработчика на C # я использую Stylecop, который обязывает комментировать все классы, методы и т. Д. Я автоматически генерирую эти комментарии с помощью инструмента. В большинстве случаев сгенерированные инструментом комментарии являются достаточными и могут быть выведены по имени объекта, например, класс Person имеет поле идентификатора.

Но если я хочу прокомментировать неочевидный метод дальше, очень легко расширить шаблонную документацию и несколько пояснений о том, что он делает. В качестве примера: у меня есть метод в моем классе Person, который возвращает FirstName + Lastname, но я добавил немного документов о том, что происходит, когда один из них отсутствует.

Вкратце: я думаю, что стандартный документ может быть вредным, если вы никогда не измените текст, предоставленный генератором. В этом случае это просто линейный шум. Но если вы видите их как шаблон, они снижают планку для предоставления хороших и полезных комментариев для вас или ваших потребителей. Не могли бы вы написать комментарии, не генерируя их автоматически? Конечно, но вы должны будете придерживаться формата (который в случае C # довольно многословен и раздражает генерировать вручную), и это снижает вероятность того, что вы действительно предоставите этот комментарий на всех ..

Избегайте тавтологии

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

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

Автоматически сгенерированная документация, которая является просто средством форматирования для вывода информации, почти востребована потребителями вашего кода. Javadoc делает это очень хорошо.

Не каждая вещь должна быть задокументирована вручную

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

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

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

Наименее искушенные пользователи не оценят это по противоположной причине; они бы этого не поняли.

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

на простой ответ «зачем генерировать документы» можно просто ответить, показывая MSDN.

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

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

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

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