Comments Matter!

Comments Matter!

“Clean code always looks like it was written by someone who cares.” — Robert C. Martin

Are you one of those developers who prefer their code to be well commented, well aligned and self-explanatory? Well, I'm one of them.

I believe it's a sin to write a code that I myself can't understand once I have written it. So, what's the first thing you look at when you are going through a code? You guessed it right. It's a well written code description. You may not judge a book by it's cover, but you definitely can judge what a code is meant for through a well written code comment.

But, isn't it a pain to write the whole template of code comment all over again? I'm here to fix that problem for you if you're a Salesforce developer and often follow the practice of adding a code comment to your Apex, LWC or Aura Code.

Let's begin with a reusable code comment template you could follow for Apex to begin with.

Apex

/**
 * @File Name          : testClass
 * @Description        : [Story/Def #] This is a sample class for code comment
 * @Author             : Neha Kumari <autho@email.com>
 * @Created On         : 26/02/2021
 * @Modification Log   : 
 * Ver       Date            Author            Modification
 * 1.0       26/02/2021      Neha Kumari       Initial Version
 * 2.0       28/02/2021      Hari              Added logic for Account Save
**/
public class testClass(){
  /***********************************************************************
  * @Description  This is a test method
  * @Param            String - Username of the account
  * @Return       String - Returns the last name. 
  ************************************************************************/ 
  public static String testMethod(String str){
    return 'test';
  }
}

Aura

codeComment.cmp

<!--
 * @File Name          : codeComment.cmp
 * @Description        : [Story/Def#] This is to show an example code commenting
 * @Author             : Neha Kumari
 * @Created On         : 26/02/2021
 * @Modification Log   : 
 * Ver       Date            Author            Modification
 * 1.0       26/02/2021      Neha Kumari       Initial Version
 * 2.0       28/02/2021      Selvam            Added logic for Account Update
-->
<aura:component>

</aura:component>

codeCommentController.js

/**
 * @File Name          : codeCommentController.js
 * @Description        : [Story/Def #] This is a sample code for code comment
 * @Author             : Neha Kumari
 * @Created On         : 26/02/2021
 * @Modification Log   : 
 * Ver       Date            Author            Modification
 * 1.0       26/02/2021      Neha Kumari       Initial Version
 * 2.0       28/02/2021      Selvam            Added logic for Account Save
**/
({
    myAction : function(component, event, helper) {

    }
})

LWC

codeComment.html

<!--
 * @File Name          : codeComment.html
 * @Description        : [Story/Def#] This is to show an example code commenting
 * @Author             : Neha Kumari
 * @Created On         : 26/02/2021
 * @Modification Log   : 
 * Ver       Date            Author            Modification
 * 1.0       26/02/2021      Neha Kumari       Initial Version
 * 2.0       28/02/2021      Selvam            Added logic for Account Update
-->
<template>

</template>

codeComment.js

/**
 * @File Name          : codeComment.js
 * @Description        : [Story/Def #] This is a sample code for code comment
 * @Author             : Neha Kumari
 * @Created On         : 26/02/2021
 * @Modification Log   : 
 * Ver       Date            Author            Modification
 * 1.0       26/02/2021      Neha Kumari       Initial Version
 * 2.0       28/02/2021      Selvam            Added logic for Account Save
**/
import { LightningElement } from 'lwc';

export default class CodeComment extends LightningElement {}

You can also clone the snippets from my GitHub Repo. Follow the link: github.com/nehakumarisaa/sfdcReusableCodeHub

Image By : https://bilisim.io/2020/04/25/clean-code-method-principles/