Javadocs

One thing I believe very strongly in is good Javadocs.

It's one of the first places that I go when I need to understand how to use a library.?? I don't attempt to understand how to use the library through my IDE's autocomplete statements or the source code.?? I often end up in the source code, but that's usually because the API has not been well-designed or well-documented.

Good Javadocs are very hard to put together because at the same time you begin to put them together you run face-to-face with the weaknesses in your API.?? So you change the API to correct the problem, and now your Javadocs need to be torn up.?? Many developers stop there and throw the Javadocs out, or turn up their nose at them because they're not a very agile thing to do.?? But to me, they're absolutely essential–with them and unit testing, you can put together some decent APIs pretty quickly–or, I guess, more accurately, as quickly as you should be putting them together.?? :-)?? Good APIs take time, and the best ones explain themselves.

Here are some of the things that I do when writing Javadocs:

  • For any class name, I wrap it with the {@link tag}, whenever and wherever it appears.?? Think about that.?? This helps keep the reader in the flow: they can always turn down the styles in their browser or take other measures to get rid of blue underlines–I don't worry about too many links–but having the ability to quickly link to the class under discussion is invaluable.
  • For any identifier, or keyword, I wrap it with the {@code} tag.?? This is just following good typographical style.
  • For every parameter, I document whether null is permitted or not.?? This forces me to figure out what to do with nulls in every situation.?? Sometimes I will realize that accepting nulls is a perfectly reasonable thing to do (more often than not–but this is a stylistic question that every developer has a strong opinion on).
  • For every @return tag, I document whether the method can return null or not.?? Every single one.
  • For personal software, I use the @since tag and supply the month, year and date.?? That helps keep me honest and shows what order I've developed things in.
  • I always try to use the @author tag with my hyperlinked email address.
  • I try to use (and wish I were better at using) the @see tag to establish a rough trail through the API.
  • I try to hyperlink portions of explanatory documentation to methods and fields that the documentation refers to {@linkplain Object#equals(Object) as I do here in this example about the <tt>Object#equals(Object)</tt> method}.?? Note the use of the {@linkplain} tag and the nested <tt>s.
  • I have a standard boilerplate Subversion-friendly Javascript hairball that I use for the @version tag (I use keyword expansion of $Revision$):

@version <script type="text/javascript"><!–
document.write("$Revision: 0.0 $".match(/d+.d+/)[0]);
–></script><noscript>$Revision: 0.0 $</noscript>

Hope this helps you think about how you document your own code.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s