Notes on guidelines for writing readable code documentation

Last weekend the team of HydroloGIS went to visit the Geomatys team in Montpellier (mostly Martin and Adrian, which have the same attitude to work on weekends that we have :) ) . Apart of having a great time with those nice guys in discussing most of the scientific issues that rule the universe, we had a very long and good discussion about geoapi/geotools coverages (but that will be the content of another post at some point).

After having been amazed by the gorgeous level and readability of their code documentation (if you can find a non well documented class in this project, Martin would probably buy you a beer for having read it all :) ), I asked them to have a chat about code documentation. Well, what follows here are some notes about that chat.

Note that this will be related to javadoc documentation.

General rules:

• Explain in you documentation why the class/method is used and how.
• the first sentence of each javadoc is a short summary of what the class/methos/variable does. That sentence is put in every field reporting summary. It should therefore never start with a paragraph tag.
• put always a first sentence, else you will end up with empty overviews in the documentation
• For methods: always start with a verb. For fields: always start with a noun. For classes/interfaces: verb or noun, on a case-by-case basis. Of course exceptions can occurr...
  
• end sentences with the dot.
• document everything, especially public items
• embed multiline code snippets in a pre tag. It will use a monospace font and write the contained parts in verbatim. Much better would be to create a taglet which could deal with formatting and coloring of the syntax.
• if there are different constructors of the class, explain how and why you would use them.
• lines should be at most 80 characters long.
  

Class annotations (minimum set to be used):

• @author obviously defines the author. It will be converted to a comma separated list of authors in the case of more than one, so avoid to put commas in the author annotation. If you want to add the affiliation o fthe author, put it between brackets.
• @since, @version a class may be there since version 1.0 and I may do some significant changes in version 2.0, in which case I upgrade the @version value to "2.0" but it doesn't allow me to remove this class. On the other hand, if I just introduced this class in version 2.0 (which would be indicated by @since 2.0) and I have not yet released this version of the software, then I still allowed to change my mind and remove this class/method.
• @see here other classes, interfaces or methods can be referenced, that are somehow related to the current one
• @deprecated defines that the class could disappear in future releases (usually the following one). Explain in this tag what the replacement is and if there is none, explain why.

Innline annotations:

• @link defines a hyperlink inside the documentation to the related class. As a rule of tumb always link to a certain class only the first time it appears in the documentation block, in order to avoid to make the docu unreadable.
• the basic syntax is {@link package.and.class.name}
• it is possible to add a text for the link: {@link package.and.class.name text}, in order to make it more readable, instead of having just the name of the class.
• link annotations are written in some monospace font and also permit the insertion of symbols like > and <.
• in the case one would not want to have a monospace font, but instead the current font of the documentation, the @linkplain annotation can be exploited
• links to methods are build the html anchor way with an #: {@link package.and.class.name#method}
• @value this link can be used for example in the case of constant variables: {@value package.and.class.name#const} will supply that value in the javadoc
• @code can be used for inline snipptes. They will be written in monospace font.

Package documentation:

• to document a package, in recent versions of java, add a PackageInfo.java file containing the javadoc to the package.

---

I wrote this mostly because I need to get more consistent in my code documentation, but I will also try to create a small guide to put on the JGrass wiki out of this and future reviews, in order to pass it to beginning developers that join our team. Learning things properly from the start is much better than forcing ourself to get them later, when there seems to never be the time.