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.

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
	*******************************************************************************************/

view raw classlevel.txt hosted with ❤ by GitHub

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;
	}
	}

view raw methodlevel.txt hosted with ❤ by GitHub

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