Commenting Tips

This article provides some advice about commenting code. Its not specific to PeopleSoft, but the examples relate to working with PeopleCode and customisations.

Commenting Principles

The point of code comments is to make code easy for other humans (including yourself) to read and refer to at a later date.

Your code should aim to be self-documenting.

This means writing your code so that things like function names, variable names and constants make it easy to understand. Comments should be used sparingly to explain code because your code should be self-explanatory. You aren't trying to teach someone how to write code. Comments throughout standard code blocks are a form of code smell. That this, they suggest the code could be written more concisely or needs refactoring due to complexity.

Remember code tells you how, and comments tell you why.

The other major use of comments in existing systems are to tag customisations and changes to delivered code.

Commenting out Delivered PeopleCode

At some point you'll need to comment out delivered PeopleCode due to a change. The general consensus is that because PeopleCode does not have version control (unless you are using a 3rd party product), you should comment out instead of removing delivered code.

The main point of this is for patching exercises later on. Remember that because comments should tell you why, you should state why you made changes to delivered code in your comments!

Here's the style I generally use for commenting out delivered code:

Rem REF99999 DD/MM/YYYY Author's Name: Comment out Delivered Code ->;
<*
... Delivered Code ...
*>
Rem REF99999 DD/MM/YYYY Author's Name: Comment out Delivered Code <-;

The Rem statements are the markers for the start and end of the change. Hopefully you are using some sort of reference number for your code changes that are tracked somewhere. The <* *> comment operators work the best as they can encompass existing comments and application designer will still perform the correct syntax highlighting for the comment block.

Comment Blocks

A lot of people are fond of using large numbers of characters (dashes, asterisks etc) to surround their comment blocks. So you see comment blocks (especially in headers) like this:

/******************************************************************************
 * REF99999 Modified Widget Y in Sprocket Z                                   *
 * Author: Developer's Name or Initials                                       *
 * Date:   DD/MM/YYYYY                                                        *
 *                                                                            *
 * Widget Y doesn't work in Sprocket Z, which is why it was changed.          *
 ******************************************************************************/

It might look nice, but I find this an absolute nightmare! Why are all those asterisks necessary? It is such a pain to put them in and get them sitting right, and they don't look the same in every editor anyway depending on tab/space settings.

Why not just have this? It's functionally the same, takes a fraction of the time to do (so you can focus on content rather than the presentation of those asterisks) and is far easier to modify later.

/*
    REF99999 Modified Widget Y in Sprocket Z
    Author: Developer's Name or Initials
    Date:   DD/MM/YYYYY
 
    Widget Y doesn't work in Sprocket Z, which is why it was changed.
*/

As with all programming, simplify when you can. Also, most editors have some form of code formatting. If that is available to you, use that. Comment formatting should be something your editor does automatically for you if possible.