Using Java Docs

Javadoc comments are a form of code documentation. You write these comments when you write the code. Later, you or other people can use these comments to understand (or remember) what this code does, and how it does it. Clear comments make code maintenance easier. Because the business logic code has a very long life, commenting the code is essential.

Class-level comments

Each service class should have a class-level comment. This comment should include:

  • What is the role and purpose of this class?
  • Who is the author (and who is current owner, if different from author)?
  • List of major version changes.

Example:

/**
* InvoiceService - contains methods to manage payments and invoices for the AbRPLMChargebackInvoice application views.
*
* <p>
* History:
* <li>18.1 Initial implementation.
*
* @author draghichi
*/

Method-level comments

Each service method should have a method-level comment. This comment should include:

  • What does this method do?
  • Which input parameters does it expect?
  • Which data values, if any, does it return?

Example:

/**
* Creates new invoice for selected costs.
*
* @param costIds The list of cost IDs.
* @param invoiceRecord The data record containing invoice data.
* @param issueInvoice Whether to issue the invoice after saving it.
*/

Code comments

You should add comments to the code that performs complex calculations or logic. These comments should explain the intent of the calculations or logic, as opposed to duplicating the mechanics of the code.

Good comment:

// find the Date Due of the last scheduled cost for this recurring cost

Not so good comment:

// use dataStatistics.getDate() to get MAX(date_due)

SQL comments

If the code runs an SQL query, the comment should explain the intent of the SQL.

Example:

// sum SERV site common area from SERV to SITE