Как вы задокументируете заявку?

Question

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

Java, похоже, хранит большую часть своей документации в исходном коде, который описывает только базовое использование определенных классов - создание объекта DecimalFormat для использования запятой, поскольку разделитель десятичных чисел является нетривиальным, если вы stik для verbose) Документация API только (насколько я понял из их документации, она включает классы DecimalFormatSymbols и Locale, но дело в том, что я не могу точно сказать без дополнительной информации). Затем пропущенные части проверяются отдельными Java tutorials, которые в основном описывают отдельные специальные варианты использования их библиотеки.

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

Я знаю, что объем библиотек здесь не то же самое, и я не искажаю Java, но думал, что это будет сопоставление документации по философии.

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

EDIT

Я думаю, мне нужно прояснить немного: Когда проект вырастает за пределы определенного (код-/Team-) размер он получает трудно других разработчиков присоединиться к нему. Я знаю, что документация по коду очень важна для понимания кода, но я не думаю, что достаточно начать работу над проектом. Либо кто-то другой должен дать ему учебник (объясняя, почему все выглядит так, как они), или его нужно где-то документировать.

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

Я не после реакции ваших коллег, но эффективность вашего процесса документации (просто упоминание реакций в качестве индикатора).

Answer 1

Во-первых, и это кажется очевидным, но не многие люди, похоже, хорошо следуют за ним - напишите self-documenting code.

Во-вторых, реорганизуйте код, чтобы его было легче читать. Классическим примером этого является Extract Method refactoring.

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

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

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

Answer 2

Я пытаюсь сохранить документацию в исходном коде. Поскольку я работаю в C#, я использую систему /// для документации. Впоследствии SandCastle может использоваться для создания документации из комментариев. Я думаю, что wiki - хорошая идея для документации на высоком уровне.

Answer 3

Мы стараемся поддерживать документацию внутри кода. Мы используем Javadoc для этого.

Doxygen - отличный инструмент для генерации диаграмм классов непосредственно с исходного кода.

Иногда, в зависимости от используемой нами платформы, мы генерируем Схемы ER через обратный рычаг. Для этого есть много инструментов.

Это документация, которую клиент получит.

Некоторые другие документы, такие как процедуры установки, как создать резервную копию системы, как сделать новое развертывание и т. Д. документально зафиксирован в Wiki-системе.

Answer 4

Должен согласиться с JamesC78. Когда я программирую на Java, я делаю обычные комментарии и JavaDocs для разработчиков. Но затем я также обновляю Wiki с некоторой документацией более низкого уровня, например, как запускать программу, что искать, какие таблицы базы данных используются, что она делает и т. Д.

Answer 5

Я прочитал и перечитал этот вопрос, как 3 раз, чтобы определить, имеете ли вы в виду документ USE вашего продукта и документируете, как разрабатывать свой продукт, а не комментировать, и в конце концов я все еще не могу сказать, за чем вы после? ;)

Теперь, когда я работаю на себя, я должен признать, что я в этом ужасен. Я комментирую свою аудиторию (меня) в основном в виде напоминаний или объяснений для себя. Иногда я получаю несколько страшную память, поэтому это полезное упражнение. Я не знаю, сколько других людей получит от моей документации, но это работает для меня. Я использую встроенные инструменты Visual Studio (///), что позволяет сделать более позднюю автоматическую документацию, подобную javadoc или кислороду. Я также активно использую // TODO:

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

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

Answer 6

Если бы это был проект Python, я бы предложил doctest.

Например, приведено описание small doctest, в котором описано, как использовать простой пакет блокировки административных файлов.

Есть по крайней мере две doctest-подобная система для Java: JDoctest и doctestj