Feb 12, 2020 by Andrei Demit
The Real Purpose of Comments in Code
Demystifying the great comments in code debate
“Never use comments in code, because it should speak for itself.”
As a .Net developer, I hear this statement more and more from people who have never written a line of comment in their life, yet they believe the statement to be true because it seems “logical.” There may be some truth hidden there, but most of the people who herald this trend don’t even recognize their own two-day-old code, let alone understand something written by someone else.
The truth is that writing and maintaining comments requires more brainpower, which is already stretched to its limits. Especially after a long session of debugging and trying to solve an issue, the last thing we want to do is to explain in simple sentences what the purpose is of a function or algorithm.
The second reason some may avoid writing comments, which is often a limit for programmers, is the lack of skills in explaining our reasoning in simple English words.
A third issue contributing to this trend is the lack of real understanding of the inner works of some portion of code. It’s this lack of understanding that can trigger the second issue (hard to explain something challenging), which, in turn, triggers the first issue (brainpower limit). The fact of the matter is, if something is understood deeply, the subject would be able to be explained in simple words. As Albert Einstein said, “If you can’t explain it simply, you don’t understand it well enough.”
Now that the real reason why some people dislike commenting has been outlined, let’s take a look at the “logical” part that wants to justify this comment-free code trend.
As mentioned previously, there is some truth or some reason which should prevent a programmer from commenting on everything that’s been coded. For a developer that knows the craft well, it can be common sense; for others, it may involve some point of view shifting.
Skipping contrived examples since it is common knowledge that real-world code is enormously more complicated than what could be shown here, consider the following.
What are the benefits of explaining the intent of a specific part of the code?
- The time dedicated to understanding a portion of code will be drastically reduced because you will already know what code is supposed to do. Indeed, this alone can save you hours after a long break, such as a holiday.
- Finding a function or a specific feature implementation will become easier as comments will guide you through the code jungle (especially when you’re dealing with an unfamiliar project).
- You can understand why a developer chose to do something in a specific way. That is useful, especially in situations where a not-so-obvious solution has been used because of business choices not evident in the code. A well-placed and straightforward intent comment will save you hours of thinking.
- Clarifying the intent of your code helps you define it better in your head. Therefore, it will be clearer what you have to do. Also, pertaining to code review, if there were to be a mismatch between the code that has been written and the intent expressed in comments, it would be easier to spot bugs that sometimes pass the code review unnoticed.
- People who are not programmers can have a say when they view the code. The comments stating the intent will help them clearly understand the logic used in the program. Indeed, this can sometimes be a source of double-checking the correctness of the business logic which has been applied.
The myth of the auto commenting code
No matter how “English-like” the syntax is of a programming language, it will never be able to express why a particular choice has been made.
When we code, an assumption is sometimes made that others share our knowledge and experience. That is just part of human psychology– it is not limited to programming. However, we must logically discipline ourselves to understand that any other person who would see our code will lack some context:
- They won’t have the same information we have
- They won’t read the code in the same order it is executed
- They won’t be oriented in the source code, and for them, it will be unfamiliar territory
- They won’t have the same technical knowledge
Any developer could experience the same issues with their own code after six months. Just try to go back to an old project and see if you understand everything clearly in the first few minutes. If you don’t have access to something like this, you can perform this experiment by trying to figure out what the first functions of any repository on GitHub do. Then write a clean-room implementation that would pass all the tests the original functions passed. Time yourself while you do it. How long did it take to do this?
Now, let’s address the worries which lurk in the minds of people who despise comments.
- Comments will become out of date and will become misleading:
That is true, but it will happen only if you let them fall out of sync. Programmers must reflect their changes in the comments, just as it is necessary to update the documentation when changing or adding a new feature. If the comments fall out of sync, this typically means that we are dealing simply with developer laziness. In the beginning, it might be hard to stick to commenting if it is something you’ve never done before, but if you build up discipline, the pay-off will be remarkable.
- Line noise in code:
Many programmers would prefer a 300-line file with commented code than 150 lines of uncommented code. This way, a programmer would understand the purpose of the code faster, and could easily refactor the code itself, such as in instances where the comments do not add value. To begin, you can start by commenting more than needed. As you improve, you’ll be able to trim a lot of the comments and maintain only the comments which add value to the code.
- A lot of time is being wasted by writing comments:
Again, we have to factor in human psychology, as well as today’s “instant gratification” society. We worry so much about losing time that we forget what is important and focus only on what gives us an immediate feeling of satisfaction or of progress being made.
Going to the gym doesn’t give instant results. But, when it’s made a habit, we reap spectacular benefits from our fitness routine. Commenting code is no different. We may feel like we’re not making progress now, that we are wasting time. Yet, when we come back to the code we wrote with the comments describing why something was made in a certain way, we thank ourselves for taking the time to explain our reasoning. In the future, we will realize the number of hours we save by having put those comments in place.
When it comes down to it, 10 to 20 minutes today will save us hours later. By the same token, as more and more programmers revisit the code, the 20-minute investment could potentially translate into hundreds if not thousands of hours saved.
- Comments will become out of date and will become misleading:
8 comment-writing guidelines to follow
For programmers to improve their craft and create value with their work, the following guidelines are recommended:
- Make an effort to understand all the code you’re dealing with. If you don’t do this, you won’t write meaningful comments.
- Never restate your code functionality in the comments. You have to express the intent, the reason behind a specific portion of code; to tell the audience why something is happening.
- Respect documentation comments.
- You may write marvelous comments, but that does not allow you to write poor code. So take care of your code by taking note of the following:
a. Variable and function names should have clear names that reflect their purpose.
b. Don’t confuse elegance with complexity. Complex code is a sort of spaghetti, elegant code is a swiss watch mechanism.
c. Don’t overdo it with the length of the lines. If you scroll horizontally too much, something is wrong.
d. Follow a consistent style in coding.
e. Follow DRY and SOLID principles, but with common sense in mind. Think like a human, not like a machine. Otherwise, you could fall in the SOLID DRY Spaghetti that is even worse than regular spaghetti. (At least the latter can be eaten).
- Comments will become out of date only if you let them.
- Never commit commented-out code. It is the real line-noise maker.
- Our comments should be a living form of our specifications. Indeed, comments should allow us to recreate the program in any other language.
- Self-commenting code should live along with intent comments, and they are not mutually exclusive. Indeed they are complementary. The code will answer the “How?” while comments will respond to “Why?” and together they will give you what you want to accomplish.
So, while it’s true that commenting in a meaningful way is hard, programmers must make the effort to build a habit out of it. Once it becomes a habit, commenting will be more comfortable and more natural. When the time comes to reap the fruits of our discipline, it will more than compensate for our initial hard work.
About the Author
Andrei Demit is a Cognizant Softvision .NET developer who believes in software craftsmanship, treating coding as one would treat making art. Through his work, Demit endeavors to inspire others and deliver real value.