Friday, March 4, 2016

Start Documenting Rather Than Accepting "No Comment"

My Auntie Pat Tern tried to convince my cousin Tim Toady that he should be using the 3/5 rule of essay writing he'd been taught -- three ideas, five paragraphs -- but, as usual, Tim insisted there is more than one way to do it (TIMTOWTDI). So I looked through the code in my Salesforce org to see if my developers were following the 3/5 rule for comments or if TIMTOWTDI had gotten into our code.  Unfortunately, I mostly found code with no comments at all.

Code without comments is like a research paper without a thesis statement to detail its purpose.  It's like doing something over and over without understanding why because comments should always clarify why it does what it does.  It's like burying treasure without leaving a proper map because good comments point to valuable resources the code uses or makes available.

Code comments should follow the 3/5 rule of comments:  there are three places where comments should occur and five specific topics that need to be addressed.

The three places where comments should be found in Apex code are:
  1. Block comments at the beginning of classes.
  2. Block comments at the beginning of methods.
  3. Line level comments for constants, loops, conditions, and where clarification is possible.
The five topics that should always be found in block comments are:
  1. Description of purpose and assumptions.
  2. Author/date for creation and modification.
  3. Parameters for methods that accept values, or none.
  4. Return values for methods that pass values, or none.
  5. References and dependencies.
Here's an example of code that follows the 3/5 rule of comments:



In this example, block comments appear at the start of the class and at the start of the methods while inline comments appear within methods and for named constants. The comments use Javadoc tags like "@description" to make the important topics easy to locate.  These comments even include "TBD" to indicate code that is incomplete and point out the limitation imposed by the choice of Integer as a data type rather than Long. Comments should always include information that may be reconsidered during the next phase of development.

We ask that developers and admins both be responsible for code comments because the admin should know how code effects data integrity and user experience.  Without that level of cooperation and understanding, admins have been known to implement validation rules that cause code to fail and developers have been known to implement code that causes user experience to decline.

Tim Toady is right, there is more than one way to do it with code.  That's why we ask for comments that explain why the code was written the way it was.  And we follow Auntie Pat Tern's 3/5 rule to make sure we have comments in three areas of code and covering 5 required topics.  Better comments lead to better collaboration and easier maintenance of the code and the org where it runs.

3 comments:

  1. Great post! I fondly remember that documentation format :) Good habits die hard!

    ReplyDelete
  2. Could not agree more!!! But the only thing I would say is within your methods you really shouldn't need comments if your variables loops and code structure are clear enough. Also actually I make sure that the class and method headers comply with ApexDoc otherwise you can't generate any documentation off them which uses very slightly different formatting (see: https://github.com/SalesforceFoundation/ApexDoc, it may actually work as is but not 100% sure) also because you're missing the *'s at the beginning of each line and the /** at the start Mavensmate shows the comments up in red as not formatted correctly.

    ReplyDelete
    Replies
    1. Thanks for the great tips, Francis, especially recommending ApexDoc. I hope people who see your comment here will consider using it!

      Also, as far as comments within the methods go, we use them for two reasons: 1) make sure we keep track of why the code was written the way it was so we don't refactor when we should not 2) make sure that nondevelopers and less experiences programmers can see how code enforces business rules because we want admins more involved with the automated processes in the org. Most of the comments within the method above address the kinds of questions that have really come up during code reviews.

      Delete