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
Method level comment

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