Javadocs: The Programmer's Friend

By Matt Brinkman

There are many levels of skill in just about any job field, and just like every other, there are good ways to start learning a new skill, and bad ways.  In a programmers every day life, it is the documentation within the code that will keep him and his coworkers sane.

Every person has different methods of remembering how something works, some people actually retain this knowledge, but it seems as if most do not.  Think of it this way, if one person was responsible for building an engine in a car, and they quit or left half way through, the task is likely wasted, whoever comes on next will have no idea where to begin rebuilding it.

Software can be seen in a similar manner, unlike a word document or even a novel that one could modify easily from brief memory, software is built around a foundation, support and inner workings.  Because software is very much like a physical working device, it is important to remember how we built it so that others can continue our work, or complete the task side by side.  Every person works differently, but if detailed enough a programmer can read another’s, often times even in a language they are not familiar with.

Since the main goal of this article is to detail one particular style of documentation, the first most important highlight of Javadoc itself is the native ability to generate HTML pages, which can easily be posted on the web for others use, and ways to interface with the code.  An important note to this is that Java itself was coded using Javadoc, which allowed Sun to post Application Programming Interface (API) right to its site, without wasting time and money converting it.  As long as the comments are descriptive enough, cost savings are likely to be successful.

As a result of this ability, it is also easy for developers to make a Java Integrated Development Environment (IDE or an all in 1 solution for Java programming) and give it code completion options that are able to adapt as commands and methods change.  For example, say we are using a version 1.0 of Java, and a 1.0 version of a popular editor; the editor can read partial commands and guess what you wanted to type, and given a command, describe what it does.  Since we can read the comments for the code, and even better if you cannot see the code (which usually have the comments stripped once compiled) if the Java language changes, so does the editors ability to assist you in efficient coding.

An additional ability as hinted above is to allow another programmer access to public functions within the program, and know how to efficiently use them, because a knowledgeable programmer implemented Javadocs while writing his portions, but because of copyright could not post the actual code.  It is now possible to integrate closed source applications from different parties, and while this isn’t amazing or impossible to accomplish otherwise, this particular language documentation can save an employer money as the support for the project comes into play.

Finally, because the specification behind the documentation is so flexible, and descriptive, there are some tedious tasks that can be avoided by simply writing the documentation first and using a third party program to analyze it and generate what is often called ‘cookie cutter code’ further increasing productivity, and decreasing costs.

In short, any program commenting is quite useful, but of particular interest is the Javadoc, which is bundled with the popular Java programming language.  As a result of its convenience, programmers can work together on a project, even years later, or if the program code is unavailable, save money when supporting, documenting, and even coding toward the finished software, and massive benefits of being flexible with the future in mind.

Sources

 

http://www.builderau.com.au/program/java/0,39024620,20278276,00.htm

 

http://www.cs.wisc.edu/~davin/courses/cs302-spring2000/javadochowto.html

 

http://www.javaworld.com/javaworld/jw-08-2000/jw-0818-javadoc.html

 

http://www.devdaily.com/java/edu/pj/pj010014/pj010014.shtml