Commenting Tips

This article provides some advice about commenting code specific to PeopleSoft. Remember that:

Commenting out Delivered PeopleCode

On occassion you'll need to comment out delivered PeopleCode. The general consensus is that because PeopleCode does not have version control (unless you are using a 3rd party product), you should comment out and not remove 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.          *
 ******************************************************************************/

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.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License