Skip to content


Coding Style

Comments & Documentation

While there is no single standard for documenting your program, classes, and functions, it is always best to adhere to practices that provide good readability for yourself and others.

Documenting Functions

Use Javadoc coding standards to document your functions. I recommend using the following structure  for your Javadoc function comments:

/**
  * func-name: Description of function
  * @param [param-name1 description of parameter
  * @param param-name2 description of parameter
  * @return description of value returned
  **/

As an example we have:

/** fib: recursive fibonacci sequence
  * @param n sequence value to calculate
  * @return the n-th value in the fibonacci sequence
  **/
long fib(unsigned long n)
  {
    if (n <= 1) {
      return n;
    } else {
      return fib(n-1) + fib(n-2);
    }
  }

References

http://java.sun.com/j2se/javadoc/writingdoccomments/

http://java.sun.com/j2se/javadoc/

Posted in .