Commenting Your Scripts

It is important that you document your scripts so that you and your colleagues who might view the code months from now will remember what the logic is doing.

You can use either a double-slash combination // which makes the rest of the current line a comment, or you can use the open-comment and close-comment combination of /* followed later by */. The latter style can span multiple lines.

Here is an example of both styles in action:

// Loop over the names in the list
for (name in listOfNames) {
  /*
   * Update the location for the current name.
   * If the name passed in does not exist, will result in a no-op
   */
  updateLocationFor(name,      // name of contact
                    'Default', /* location style */
                   )
}

When using multi-line comments, it is illegal for a nested /* ... */ comment to appear inside of another one. So, for example, the following is not allowed:

// Nested, multi-line comment below is not legal
def interest = 0
/*
  18-MAY-2001 (smuench) Temporarily commented out calculation!
 
  /*
   * Interest Accrual Calculation Here
   */
   interest = complexInterestCalculation()
*/

Instead, you can comment out an existing multi-line block like this:

// Nested, multi-line comment below is legal
def interest = 0
//
// 18-MAY-2001 (smuench) Temporarily commented out calculation!
// 
//  /*
//   * Interest Accrual Calculation Here
//   */
//   interest = complexInterestCalculation()
//

Or, alternatively had your initial code used the // style of comments, the following is also legal:

// Nested, multi-line comment below is not legal
def interest = 0
/*
  18-MAY-2001 (smuench) Temporarily commented out calculation!
 
  //
  // Interest Accrual Calculation Here
  //
  interest = complexInterestCalculation()
*/

The most common style-guide for comments would suggest to use multi-line comments at the beginning of the script, and single-line comments on subsequent lines. This allows you to most easily comment out code for debugging purposes. Thus, you typical script would look like this:

/*
 * Object validation rule for BankAccount
 * 
 * Ensures that account is not overdrawn
 */
def balance = CurrentBalance
// Use an object function to calculate uncleared charges
def unclearedCharges = unclearedChargesAmountForAccount()
// Perform some other complicated processing
performComplicatedProcessing()
// return true if the account is not overdrawn
return balance > unclearedCharges