Documentation of your code

Posted: July 27, 2008 in Best Practice
Tags:

Documentation is a very important aspect in writing programs. Coders like to code; coders don’t like to write. It’s no secret that thorough and approachable documentation is a rarity in the coding world. Despite its necessity for the adoptability of a given software package, finding Sorry to say this folks, but employees leave. They get better jobs, or get fired, or for some reason or another leave your organization. By having your coders maintain well written documentation you give yourself two advantages:

  1. You protect yourself against workers leaving with legacy application knowledge, and
  2. You shorten the ramp-up time of the new employees that take over the application.

You should always imagine that you are working within a group of people, and each one of you should be able to understand each other’s code in a matter of seconds. Even if you decide to read your own code after a few months, it is nearly impossible to do so without proper documentation.

After reading this we know the necessity of documentation. But before documenting of our code we must set the structure of documentation that are acceptable to clients and how can someone other than me can understand my code without going into much details about the code.

Lots of tools are also available for documentation of code. These tools work correctly if we are commenting our code in a desired format that tool support. If we are talking about ‘ActionScript’ code documentation than most of the tool support JavaDoc commenting style. So we must follow certain rules in our doc comments.

  1. Rule #1 : Who has a doc comment
    Every declaration of a non-private interface, class, constructor, method or field must have a doc comment immediately before it.
  2. Rule #2 : First sentence
    The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the declared entity (class, method, whatever) being documented. This sentence must end with a period followed by a newline. However, this sentence may span multiple lines and may be followed by additional sentences. For example:
    /**
    * The JavaEyes class is a Java-based implementation of the
    * familiar "xeyes" program, available on many Unix-based systems.
    * Each JavaEyes object is a pair of "eyes" whose eyeballs
    * follow the movement of the mouse.
    */
  3. Rule #3 : Required Tags
    There are special tags that can be used in Javadoc to indicate that a specific type of information is about to be given. There are many tags, but we require only these:
    • @author   name
    • @param   parameter-name   parameter-description
    • @return   return-description
  4. Rule #4 : Order of Tags
    Include block tags in the following order:

    * @param       (classes, interfaces, methods and constructors only)
    * @return      (methods only)
    * @exception   (@throws is a synonym added in Javadoc 1.2)
    * @author      (classes and interfaces only, required)
    * @version     (classes and interfaces only, required. See footnote 1)
    * @see        
    * @since      
    * @serial      (or @serialField or @serialData)
    * @deprecated  (see How and When To Deprecate APIs)

  5. Rule #5 : Placement of tags
    All tags should begin at the start of a new line of a doc-comment, per the examples above.
  6. Rule #6 : html
    You may use html tags (like <code> xxx </code>) within the doc comment to provide additional formatting of your comments. Not all html tags will work, but the most common will.
  7. Rule # 7 : additional content
    You may put comments into your program that are not doc comments. While the doc comments form the official public release documentation, other documentation may be useful during development.

Here is the example of commented code.

/**
* Sets the position of the target object to a specific x,y location on the screen
* @param xPos The horizontal position on the x axis to place the target
* @param yPos The vertical position on the y axis to place the target
* @throws IOException If an input or output exception occurred
* @see moveTargetBy
* @see public function repositionTarget(Void):Void
* @return True if the positioning is successful, False otherwise
*/
public function positionTarget(xPos:Number, yPos:Number):Boolean {
    // function body
}

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