Написание документации к коду задача не самая простая и уж точно не самая приятная, но к счастью существуют инструменты которые могут существенно упростить эту процедуру. Для этих целей я использую инструмент Doxygen и именно о нем пойдет речь.
Что такое Doxygen?
Doxygen – это кроссплатформенная система документирования кода с поддержкой языков C++, C, Java, Objective-C, PHP, C# (список можно уточнить на сайте проекта).
Для создания документации достаточно просто писать комментарии в коде, придерживаясь нескольких простых правил.
Doxygen умеет анализировать исходный код проекта и создавать удобную документацию в формате HTML, Latex, RTF, XML, man, CHM.
Общие соображения
- Написание документации должно быть максимально простым, чтобы разработчики не "забывали" это делать. Отсюда вывод, что сложность форматирования комментариев должна быть минимальной.
Хорошо:
namespace A { /** Имя класса Описание класса */ class B { }; }
Плохо:
namespace A { /** * Имя класса * * Описание класса */ class B { }; }
Почему второй вариант хуже? Очевидно, из-за необходимости выравнивать комментарии на одном уровне с комментируемой сущностью, а также из-за избыточных символов *. Это может показаться надуманным, но при написании комментариев из нескольких строк проблема проявляется, а при поддержке кода и вовсе становится кошмаром. Вы можете возразить, что подобный стиль делает код "рваным", но в любом случае комментирование интерфейсов делает код менее читаемым. К счастью все современные редакторы кода позволяют легко свернуть блоки с комментариями, что позволит взглянуть на код без помех.
- Много документации – плохо, так как мало кто будет читать длинные мануалы. Из этого следует, что документированы должны быть только открытые (public) и защищенные (protected) интерфейсы. Закрытые (private) интерфейсы – часть внутренней реализации и не должны быть в руководстве.
