Как документировать C++ проект?

Question

[Марат Нагаев]

Есть рабочий проект на C++, примерно 20к строк. Есть ощущение, что документирование только с помощью Doxygen это недостаточно - структура классов это конечно здорово, но для новичков имхо разбираться в коде будет сложно. Может имеет смысл посмотреть куда-нибудь в сторону UML?
Хочется описать не только отдельную функцию и/или класс, но и какой-то модуль.

Comments

[Adamos]

Чтобы с проектом могли разобраться новички - нужно не отягощать Doxygen диаграммами, а дополнить его информацию "ЧТО делается в проекте" текстом на тему "ЗАЧЕМ это делается".

[Марат Нагаев]

Adamos, Просто текст прям в маркдауне каком-нибудь?
Я о таком думал, но md похоже подходит только для очень верхнеуровневого описания.
Хотя хз

[Adamos]

Марат Нагаев, смотря какого объема проект.
Может, достаточно ридми, а может найтись материала и для вики.

[calculator212]

Марат Нагаев,

Просто текст прям в маркдауне каком-нибудь?

В целом этого и тестов почти всегда достаточно. Если есть какой-то нетривиальный алгоритм или логика, то можно отдельно описать это. Если считаете, что нужно составить диграмму классов, то составляйте в проекте на 20к строк кода, на это уйдет от силы день. Но потом вам придется постоянно её поддерживать

Хочется описать не только отдельную функцию и/или класс, но и какой-то модуль.

Ну так можно также создать readme и описать, что делает класс. Можете посмотреть как это делается в opencv, на мой взгляд относительно 90% на плюсах у них хорошая документация.

Answer 1

[Василий Банников]

Может имеет смысл посмотреть куда-нибудь в сторону UML?

UML на практике мёртв. Лучше посмотри в сторону C4 model.
И то максимум до третьего уровня (component diagram). Часто хватает даже второго уровня (container diagram).
Четвёртый уровень (code diagram) слишком сильно детализирован и его слишком тяжело поддерживать в актуальном состоянии.

А лучше ещё сделать пару страничек на внутренней вики с объяснением, что это вообще за проект и что он делает.

Answer 2

[Kaban_Kanban]

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

Если вспомнить умозаключение Боба Мартина из книги "Чистый код". Чистый код не требует документирования или требует, но не значительного. Чистый код — это код, который легко читать, понимать и изменять другими разработчиками. Он является выразительным, кратким и организованным.

В своей практике я встречал 3 подхода к документированию:
- Нет документирования (лишь комментарии к отдельным блокам кода)
- Документируют, но только то что захотели
- Документируют все

Когда я документирую что-либо я стараюсь показать 2 вещи:
- структуру без реализации (реализацию можно посмотреть в коде)
- бизнес задачу/ бизнес подход (для чего это нужно?)

Читал статью (оч. давно) про чрезмерное документирование... Но ни разу не встречал.

Чаще всего я видел документирование через MarkDown, UML, OpenAPI, Swagger, просто использование интерфейсов.

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

UML отлично подойдет для описания отношения (классов/объектов) или для взаимодействия модулей. Ни разу не использовал UML для описания (функций/методов), но почему бы и нет? Были случаи когда я использовал просто блок схему для описания поведения (функции/метода)...

Создавая любой вариант документации нужно продумать процесс поддерживания ее актуальности.

Comments

[Adamos]

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

[Kaban_Kanban]

Согласен! Само документирование сложный вопрос. И описывать взаимодействие сложных модулей (возможно) не совсем правильное решение. Так как сложный модуль всегда может быть изменен, а документация нет. Банально человек забыл, а ревьювер не вспомнил. Самый правильный подход на мой взгляд - упростить код. При таком подходе будет проще поддерживать кодовую базу и читабельность будет на высоте.

Answer 3

[maaGames]

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