Why an asterisk prefix on every single JavaDoc line?

Question

What is the reasoning behind putting an asterisk before each and every line in a JavaDoc block? While it seems to be the encouraged and accepted convention, and I've finally succumbed to doing it, it certainly doesn't make my writing of documentation any faster (despite tools that assist in creating them, such as the DocBlockr plugin in Sublime).

A clear benefit to having the lines in multi-line comments not exceeding around 75 characters, is that your code can more easily be shared, without having to tweak it, and without viewers having to scroll to the right to read your docs.

But why take this a step beyond that, and have this extra convention? Padding spaces to the left side could be done with an optional asterisk prefix... Why every line?

Answer 1

It is a stylistic convention ... though the javadoc command does (apparently) treat the cases of leading * and no leading * differently in some circumstances.

The Sun Java Style Guidelines describe the convention in section 5.2.

Why? Well, the real answer(s) can only be provided by the people who developed the Java style guide.

However, my guess is that they thought that it makes the javadoc comments stand out better.

---

Padding spaces to the left side could be done with an optional asterisk prefix..

Erm ... it is optional. You are not required to follow the convention, unless your project's style guidelines say that you do.

It would nice to know why I have to spend an extra keypress or three on every single line of documentation I have ever and will ever write.

Ask the folks who developed the IDE you are using :-)

Answer 2

I have nothing to proof this, but I always attributed it to the time, when everything in the world was black or white (i.e. black or green) actually. In those times you couldn't easily differentiate between code and comments.

Those asterix prefixes made it really easy to identify the part of the file, that you can safely ignore.