How to comment your apex code (sample templates)

Commenting your code well is very important for maintenance of your code. In software field it is very common for developers to change jobs very often. So it is very important to keep the code maintainable and understandable with good comments.

Comment Apex Code

Things to Notice

Primary intent of comments is to make your code self documenting

At a minimum add class and method level comments explaining what is the purpose of the class/method. Additional comments should be added on places where explanation/clarification is required.

Don't overdo it

We can see people adding comments every line or every other line. That is also unnecessary. It just makes reading through code more time consuming. Please keep in mind, intent of comment is to make somebody understand what is going on in code. Add granular details only if you feel an average developer might need comments to understand the logic.

Samples

You can use below sample templates as class and method level comments:-

Class level comment

/*******************************************************************************************
* @Name         CacheService
* @Author       FirstName LastName <author@email.com>
* @Date         09/20/2017
* @Group        Cache Services
* @Description  This class contains all service methods related to caching data in Salesforce.
*				It is segregated as a service to make changing cache partition easy.
*******************************************************************************************/
/* MODIFICATION LOG
* Version          Developer          Date               Description
*-------------------------------------------------------------------------------------------
*  1.0              Firstname      09/20/2017          Initial Creation
*******************************************************************************************/

Method level comment

/**************************************************************************************
* @Description  This method gets checks for entries in org cache and returns it
* @Param		String - Key string
* @Return       Object - Value retrieved from org cache.
* @Example
* CacheService.getFromOrgCache('accessToken')
**************************************************************************************/
public static Object getFromOrgCache(String cacheKey) {
    if (Cache.Org.contains(cacheKey)) {
        return Cache.Org.get(cacheKey);
    }else {
        return null;
    }
}

These examples follow ApexDoc syntax requirements. ApexDoc is a java application that is used to generate code documentation from code comments. It follows Javadoc style. If you are following the ApexDoc comment pattern, you will be able to generate static HTML documentation from the code by following instructions in ApexDoc documentation. You can find ApexDoc source and instructions in the repo - https://github.com/SalesforceFoundation/ApexDoc

[Top]