Commenting and Documenting Application Classes

This section contains guidelines for writing method header comments, class header comments, and tags inside the comments.

Documentation is important in all code, but even more so in application class code, which aims at, and incurs certain overhead in the name of, higher levels of reuse.

There are two types of inline comments:

Internal comments, which start with /* and end with */.
Comments which can potentially be used to generate API documentation, which start with /* and end with */. You can write method header and class header comments for application classes, and you can use the comment tags, with this type of comment.

Warning! In application classes you will see the use of /+ +/ style comments. Do not use these in your PeopleCode. These annotations are generated by the compiler. If you use them, they will be removed the next time you validate, compile, or save your PeopleCode. They are used to provide signature information on application class methods and properties, and are regenerated each time the compiler compiles your application class PeopleCode. Instead, use the standard commenting mechanisms listed above.

PeopleSoft recommends keeping a running line of asterisks along one side of an extensive comment to help the readability of the code by making the entire comment stand out from the surrounding code.

The following is an example of documentation conventions for method header comments, which are also suitable for PeopleCode. It contains comment tags, which are explained below the example.

/**
  * Description of what method does
  *
  * @param a optional description of param a
  * @param b optional descriptions of param b
  * @exception PrivilegeException thrown if etc, etc
  * @exception SQLException thrown if etc., etc.
  * @return String  -  description of potential values
  */
Method myMethod
   ...
End-method;

Method Comment Tags

The following are the suggested tags for commenting methods.

Tag	Description
@param `N`	Specify a description for each method parameter. The name of the parameter is specified after the keyword @param.
@exception `name`	Specify a description of each exception class. The name of the exception is specified after the keyword @exception. For example, the descriptions can explain what causes certain exceptions to be thrown.
@return `Type`	Specify a description of the return value. The type of data that is returned is specified after the keyword @return. For example, explain the potential values a method may return, whether it returns null in some circumstances, and so on.

Not all methods require documentation. For example, some simple set or get methods have method signatures that are descriptive enough. In other cases, it may suffice to include a brief sentence in the header explaining what the method does.

As with methods, PeopleCode get or set blocks should also carry method header comments.

Header comments for the class should provide descriptive information about the class, and may optionally include additional tags, indicating version and author:

/**
* class description
*
* @version 1.0
* @author amachado
*/

Class Header Comment Tags

The following are the suggested tags for commenting class headers.

Tag	Description
@version `number`	Specify a version number for a class.
@author `name`	Specify an author for a class.

Commenting and Documenting Application Classes

Understanding Comments and Documentation

Method Header Comments

Method Comment Tags

Class Header Comments

Class Header Comment Tags