Doxygen for Mac - Download

Так ты разработчик, да? У вас есть солидная кодовая база, но никто никогда не будет ее читать, пока вы не напишете документацию. И Бог поможет вам, если вам придется делать это вручную. Вот тут-то и приходит на помощь Doxygen. Я использовал его в нескольких сторонних проектах, в основном на Python и C++, и, честно говоря, он сэкономил мне часы. Он просто сканирует ваш код, извлекает комментарии и создает чистые HTML-страницы со списками функций, иерархиями классов и даже графами вызовов. Никакой магии, но это работает.

Хорошие вещи

Что меня действительно поразило, так это то, как быстро мои беспорядочные комментарии превратились во что-то действительно полезное. Например, у меня был заголовочный файл с 15 функциями, все задокументированные с помощью /// или /** */. Запустите Doxygen, бум - HTML-сайт с возможностью мгновенного просмотра. Нет необходимости копировать и вставлять в вики или сохранять отдельный файл уценки. Результат тоже выглядит прилично – не кричаще, но функционально. Если вы работаете в команде, это намного проще, чем пытаться объяснить, что делает каждая функция, с помощью сообщений Slack. Кроме того, он поддерживает несколько языков, поэтому он предназначен не только для C++, как некоторые инструменты, которые я видел.

Не очень хорошо

Да, это бесплатно — и это здорово, — но кривая обучения не равна нулю. Файл конфигурации (Doxyfile) поначалу может показаться сложным. Вам нужно настроить пути, выбрать форматы вывода, настроить видимость символов… мне потребовалось две попытки, прежде чем вывод PDF заработал. И графического интерфейса нет. Просто командная строка. Так что, если вы ненавидите терминалы, это может показаться неуклюжим. Кроме того, сгенерированные документы являются точными только в том случае, если ваши комментарии верны. Если вы пропустите документирование функции, Doxygen не догадается, что она делает. И этот инструмент не очень хорошо интегрируется с IDE — вам придется запускать его вручную или писать скрипты. Не ужасно, но и не гладко.

Итог

Если вы пишете код, к которому будут прикасаться другие люди — будь то личный проект или командный репозиторий — Doxygen для Mac — Download for Windows стоит скачать. Это бесплатно, работает и сокращает количество вопросов «что вообще делает эта функция?» хаос. Это не самый яркий инструмент, но он выполняет свою работу без суеты. Пропустите его, только если вы пишете одноразовые сценарии или ненавидите инструменты CLI. В противном случае попробуйте. Позже вы скажете себе спасибо.