JavaDoc Style Question

[Roedy Green]

How do you do the JavaDoc for methods of this form:

/**
* get bold version of description.
*
* @param desc description of this link.
*
* @return bold version of description.
*/
private static String bold( String desc )
{
return "<b>" + desc + "</b>";
}

There should be some standard way of doing them that does not have
redundant wording. I almost think such method don't deserve JavaDoc
at all. The JavaDoc on getters almost never tells you anything useful.
The docs come out like some old Monty Python sketch based on
belabouring the obvious.

 

[Stefan Ram]

* get bold version of description.
* @return bold version of description.
There should be some standard way of doing them that does not have
redundant wording. I almost think such method don't deserve JavaDoc

It's the law:

»Omit @return for methods that return void and for
constructors; include it for all other methods, even if
its content is entirely redundant with the method
description.«

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Also, you should use »gets« instead of »get«:

»Use 3rd person (descriptive) not 2nd person (prescriptive).
The description is in 3rd person declarative rather than
2nd person imperative.
Gets the label. (preferred)
Get the label. (avoid)«

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

I am using a preprocessor, so I might write

$define RESULT bold version of description

* get RESULT
* @return RESULT

But I do not actually do this. The preprocessor, would
be nicer, if one could write:

* get »bold version of description« (=»RESULT«)
* return RESULT

To get the preprocessor output:

* get bold version of description
* return bold version of description

Or, even better, a two-pass preprocessor

* get NEXT-RESULT
* return »bold version of description« (=»RESULT«)

 

[Thomas Hawtin]

How do you do the JavaDoc for methods of this form:

I would probably write it as:

/**
* Returns bold version of {@code description}.
*/
private static String bold(String description) {
return "<b>" + description + "</b>";
}

Possibly, or even probably, I might add the @param, but I don't think it
helps much. There is form in the Sun API docs for using "Returns..." as
the description and missing out the @return, IIRC.

There should be some standard way of doing them that does not have
redundant wording. I almost think such method don't deserve JavaDoc
at all. The JavaDoc on getters almost never tells you anything useful.

javadocs do tend to include significant quantities pointlessness.
Pointless documentation is far worse than no documentation at all. It's
like the interactive "help" that gives help on a button labeled X by
saying "This button does X."

Of course removing getters and setters by better use of encapsulation
removes a good chunk of the problem.

Tom Hawtin

 

[RedGrittyBrick]

... removing getters and setters by better use of encapsulation ...

I tend to trip over phrases like this and then sit and wonder "WTF does
Thomas mean?"

I thought getters and setters *were* part of a better use of
encapsulation (as compared with exposing properties say).

 

[Lew]

I am using a preprocessor, so I might write

$define RESULT bold version of description

* get RESULT
* @return RESULT

I sort of like the Javadoc redundancy.

IDEs like NetBeans and, IIRC, Eclipse, let you edit the templates for the
auto-generation of new classes and property accessor methods. So I added
boilerplate Javadoc in my IDE's accessor template that covers roughly four out
of five attribute declarations, with minor editing for the rest. Now all the
effort is pushed off onto those reading the Javadocs instead of me.

If I preferred, say, Thomas's style for Javadocs I'd edit the templates
according to it instead.

I also put version-control meta-information (e.g., "$Id$") in my boilerplate
comments for new classes.

 

[Thomas Hawtin]

I thought getters and setters *were* part of a better use of
encapsulation (as compared with exposing properties say).

They're a sticking plaster over bad design. Yeah, there are some things
you can do over exposed fields (chiefly validation), but one is still
defining the type in terms of fields instead of coherent operations.

It's like singletons making people feel better about static variables,
whilst only adding obscurity.

Tom Hawtin