- Please don't put empty javadoc like
/**
* @param a
* @return
*/
vod foo(int a) { ... }
It occupies screen for no good purpose, it blocks elaborately defined
javadoc on the base class from showing up (if any.) Put javadoc only
when you are going to write something. If your IDE puts this
automatically, please consider turning that off.
- Similarly, please don't copy the javadoc from the base class. If a
derived method doesn't have any javadoc, the javadoc tool will
automatically copy that from the base class. If there's no javadoc,
programmers can tell that they are the same as the base class (most
modern IDEs show a little icon that tells whether this method is
overriding one in the base class, so this is very easy.)
Copied javadoc can get out of sync, and readers also have to wonder if
they are any different from base classes, since those differences are
what we pay attention to. Lastly, they occupy screen unnecessarily.
--
Kohsuke Kawaguchi
Sun Microsystems kohsuke.kawaguchi_at_sun.com