Writing Comments? Focus on Why, not What!

Last Updated on April 15, 2019 by Rakesh Gupta

Good code is self-documenting – so the adage goes!

Comments and codes have inverse relationship – it is believed that better codes need less comments! Only when one reaches a point – where, it would be difficult to grasp the underlying logic without few clues, should one resort to adding comments. This is true; but, is it always true?

The use case for writing comments – when you write large amount of codes, it might be difficult for others – including you, for that matter! – to remember why were the codes written in the first place! At such junctures, having comments as a guide posts can be a time-saver.

Before we take a deep dive into why one needs to write comments around codes – and explore different types of comments – let me draw your attention to my previous article Bugged by Bugs? Master Debugging! In the article, I discuss how to debug your code using Developer Console; it is also a good first step in understanding when, and how, to use comments!

This is fourth article in learning Apex series. If you have not read previous articles – Mastering Apex Variables – a Stepping Stone in your Apex Journey and Pre-requisites for Learning Apex – Logical Mind and Confidence! – I strongly recommend going through them now. Also, there are few assignments for you in the articles; go ahead! take a crack at it right now! It should not take you more than 30 minutes to complete them. Irrespective of whether you are a newbie, just starting a career as a Salesforce Developer, or have some programming background, completing the assignments will help you to – (1) either learn few new things; or (2) at the least, help you to brush up your concepts. At a bare minimum, these articles and assignments will help you to brush up your basic concepts of programming. Good Luck!

My primary purpose, through this and other blogs, is to be your guide and a mentor. As for Apex learning tools – such as browsing through Apex content to get you started on learning the language – there is no shortage of material available on the Web. For example, search for ‘best practice to write Apex trigger’ and you will end up with hundreds of article links. If, however, you fail to start your journey with a right mindset, it is unlikely that you will go far by practicing the codes and triggers mindlessly. So, let us start your Apex journey strategically.

The Heart of the Matter

In this article, we will look at – (1) why we need to add comments to our code; (2) understand different types of comments; and, (3) learn how to leverage its power! Let us take a real-world scenario. While driving, you may have seen many signs on the road to help drivers – like signal, speed limit, milestones or route direction. When do we need/read signs? When things go wrong! As long as we are chugging along happily, who has time to read signs?

Similar logic applies in the development environment. As long as codes work who reads comments? Challenge starts when either – (1) the code stops working; (2) customers want modifications to existing codes; (3), the code is written by someone other than you; or (3) worse! – it could be your ancient, developing, self (oouch!).

If you write codes to be consumed by other programmers first, and by the compiler second, you may find the need for additional comments to be greatly reduced. How does a software programmer comment to his/her code?

• Beginner programmer: comments explain how the code works
• Experienced programmer: comments explain why the code works
• Hardcore programmer: comments explain why other implementations were not chosen

Mainly, there are two types of comments – documentation and clarification.

Documentation Comments

Documentation comments are akin to user manual; they are primarily intended for an app’s user as opposed to fellow developers. For instance, you build a Github library or an AppExchange application. To deliver a pleasant user experience, you add crisp instructions on the best and easiest way to install the app. Whereas an app user may be grateful for a well-written user manual, a fellow developer may find the information less helpful; for, he/she may be looking for code clarification comments.

Clarification comments may include topics like why a particular tack, as oppose to other approaches, was opted in writing a piece of code while developing the app. Because the targeted audience of Documentation and Clarification codes are different, a clear distinction between the two is essential. Without clear demarcation between the two types of codes, app documentations may generate confusion and frustration among all stakeholders – to say the least.

Clarification comments

As alluded above, clarification comments are intended for anyone, including yourself, who may need to maintain, re-factor, or extend codes. If one subscribes to the adage that good code is self-documenting then, presence of too many clarification comments may raise a red flag.

Use cases for clarification comments include:

1. When you are working in a team with other programmers, the well commented functions/logics are helpful to other programmers to understand the code better. They can easily understand the logic used behind the process of solving the problem at hand.
2. When you need to recollect the logic that you used while writing that code in the first place! At times, I too forget to add comment to my codes – mea culpa!; and then, I leisurely repent, few days or months later, when I have to spend undue amount of time and energy trying to recollect the underlying logic behind the code.

Take away from the article is to develop and maintain a discipline of always adding clarifying comments to your codes. It will save you, and your team, time and frustration. Writing crisp comments may take time, but it is not only best practice but it also maintains international standards – for, in the age of globalization, you may never know who may need to reconstruct the code.

Where do we go from here?

Perhaps that is the dirty little secret of code comments: to write good comments, you have to be a good writer. Comments are not code meant for a compiler; they are words meant to communicate ideas with other programmers. Writing well, meaningful comments, is hard. It is as much an art as writing the code itself; maybe even more so. Follow these best practices while adding comments to your code: 

1. In the beginning of any code, you should describe the purpose of writing the code (functions, logics etc.) with the team members’ names.
2. Always use inline comments on code blocks that are complicated or may appear unclear.
3. Always write comments describing the intent or reason why a piece of code exists.
4. If you are going to make any changes in a function written earlier, you should describe what changes you are making and why.

Codes can only tell you how the program works; comments, on the other hand, convey why a program works the way it works! Therefore, no matter how simple, concise, and clear your code may end up being, it would be difficult, if not impossible, for even a well-written code to completely eliminate the need for well-written comments – notwithstanding the adage that well-written codes are self-documenting!

That is it for today’s blog. In the next article, I am going to discuss Making decision in programming.  

Technical Editor and Proofreader: - Munira Majmundar

Please feel free to share it with your family, friends, and colleagues!