Javadocs без HTML
Книга Robert C. Martin Чистый Код содержит следующее:
HTML в комментариях исходного кода является отвращением [...], Если комментарии будут извлеченными некоторым инструментом (как Javadoc) для появления в Веб-странице, то это должна быть ответственность того инструмента а не программист, для украшения комментариев соответствующим HTML.
Я отчасти соглашаюсь - исходный код, конечно, выглядел бы более чистым без HTML-тэгов - но как Вы делаете достойно выглядящие страницы Javadoc затем? Нет никакого пути даже к отдельным абзацам, не используя HTML-тэг. В руководстве Javadoc говорится это ясно:
Комментарий документа записан в HTML.
Есть ли некоторые инструменты препроцессора, которые могли помочь здесь? Синтаксис скидки с цены мог бы быть соответствующим.
2 ответа
Я согласен. (Это также причина, по которой я категорически против «блоков комментариев XML» в стиле C #; Javadoc DSL по крайней мере предоставляет некоторую escape-последовательность для сущностей верхнего уровня!). С этой целью я просто не пытаюсь сделать javadoc красивым ...
... в любом случае, вас может заинтересовать Doxygen. Вот очень быстрый пост Doxygen против Javadoc . Это также поднимает вопросы, которые вы делаете: -)
HTML - это не то, что я хотел бы видеть в "обычных" комментариях. Но для таких инструментов, как JavaDoc, HTML добавляет возможность добавлять информацию о форматировании, буллет-поинты и т.д....
Я бы разделил эти две вещи:
- комментарии к коду, не относящиеся к JavaDoc, предназначены для программиста, который поддерживает или улучшает код, о котором идет речь. Он должен копаться в существующих источниках, и любой HTML в комментариях просто не облегчает работу. Поэтому запретите его в обычных комментариях.
- javadoc-комментарии используются для создания документации. Используйте HTML там, где это помогает. Но очень ограниченного подмножества HTML должно быть достаточно.