vrijdag 30 maart 2012

Javadoc confusion

As a programmer you often need to look into the documentation. This is of course necessary to know what the code does and how to properly use supplied code. Expecting proper documentation is one of the 'high' standards I assume is provided in code. After all communication is the most important aspect of collaboration.

Javadoc is the standard when writing Java code. A proper Javadoc should look like this:
/**
 * Generate an informational page of this class in the supplied format.
 * Valid formats are "html" and "plain".
 * @param format The format to create the page in.
 * @throws FormatUnknownException If the format supplied by "format" is unknown.
 */
public Page createInfoPage(String format)
{
    ...
}
Everything should be documented so one doesn't have to look at the source code to know what the code does.

To my amazement I found this in the Javadoc supplied by Oracle:
Throws:
NamingException - if a naming exception is encountered
Really? This is not useful at all. How am I supposed to know how to prevent this exception or how do I present this to my users? "Something went wrong?"

As a bonus I'm going to leave this here, just something I found when reviewing code as an assignment for school. I just didn't know whether to laugh or to cry.

/**
* Returns a short description of the servlet.
*/
public String getServletInfo() {
    return "Short description";
}