CODEWITHSUNDEEP
htmlcommentsjavadoc
Joonas Pulakka
Joonas Pulakka

Reputation: 36577

Javadocs without HTML

Robert C. Martin's book Clean Code contains the following:

HTML in source code comments is an abomination [...] If comments are going to be extracted by some tool (like Javadoc) to appear in a Web page, then it should be responsibility of that tool, and not the programmer, to adorn the comments with appropriate HTML.

I kind of agree - source code surely would look cleaner without the HTML tags - but how do you make decent-looking Javadoc pages then? There's no way to even separate paragraphs without using a HTML tag. Javadoc manual says it clearly:

A doc comment is written in HTML.

Are there some preprocessor tools that could help here? Markdown syntax might be appropriate.

Upvotes: 6

Views: 1272

Answers (2)

Axel
Axel

Reputation: 14169

HTML is nothing I'd like to see in "normal" comments. But for Tools like JavaDoc, HTML adds the possibility to add formatting information, bullet points etc...

I would distinguish these two things:

  • non-javadoc code comments are for the programmer who maintains or enhances the code i question. he has to dig through existing sources, and any HTML in coments just doesn't make things easier. So, ban it in normal comments.
  • javadoc-comments are used to generate documentation. Use HTML where it helps. But a very limited subset of HTML should suffice.

Upvotes: 0

user166390
user166390

Reputation:

I agree. (This is also the reason why I am -strongly- opposed to C#-style "XML comment blocks"; the Javadoc DSL at least provides some escape for top-level entities!). To this end I simply do not try to make the javadoc look pretty...

...anyway, you may be interested in Doxygen. Here is a very quick post Doxygen versus Javadoc. It also brings up the issues that you do :-)

Upvotes: 3

Related Questions