Today we are going to talk about writing code comments. I will share my view on comments and provide you with some best practices (or worst?) for commenting code.
Why do we write code comments?
In theory, we use comments to explain some complex or not clear enough parts of our code. We aim to make them easy for understanding for the other developers and us in the future.
Everything sounds great, but in practice, things get a lot different. Reality shows that we often write comments to explain a poorly written code that we are lazy to refactor. That’s a pure truth. So in most cases, existing comments are entirely useless and should not even exist.
In my view, it is better to know when not to write a comment instead of when to write one.
Do I hate writing code comments?
Sure! But I don’t think that they are useless. Comments are like salt. You should be very careful when and what amount you are adding.
I hate when I open a code file, and Visual Studio lightens up entirely in green. In most cases like this, you should be ready to read poorly written, bloated, and complex code with not-so-well-supported documentation. Cheers!
So when not to write comments?
Do not comment already clear code
Check this:
// Setting the new password to an empty string.
var newPassword = “”;
Do you find it helpful? Of course not. The problem with this pointless comment is that after describing the 100th variable, your code becomes very hard to read. You lose readability in a trade-off of… nothing.
You can relate that rule to any comment regarding classes, methods, parameters, etc. Here is another example:
// We validate all promotion rules to check if a user is eligible for the promotion.
private void ValidatePromotion()
{
// Validates promotion dates.
ValidatePromotionDates();
// Validates promotion quantity.
ValidateOrderedQuantity();
// Validates the user member type.
ValidateUserMemberType();
}
Do not comment self-explanatory code.
Do not translate code into comments
Often you will see some simple algorithm described with multiple comment lines. This rule is part of the one above, but it deserves its place because it is widespread. Here is an example.
// We iterate over each product in the user's shopping cart.
// For every product, we check if there is a discount based on the product and the user member type.
// We return the product discount and calculate the total amount.
var totalDiscountedPrice = 0m;
foreach(var product in cart.products)
{
var priceWithDiscount = discountService.GetProductDiscount(product.id, user.MemberType);
totalDiscountedPrice += priceWithDiscount;
}
When you catch yourself translating code into comments, stop! Either you do not need the comments, or you have to refactor the code.
If the nature of the code/algorithm is complex enough, again, refactor, refactor, and only after that write comments if they are needed.
If your comment is not clear enough, don’t write it
If you can not explain something simply, that may be a sign of a bigger problem. Don’t write unclear and lengthy comments. Check your code. In most cases, you will find a need for refactoring.
Don’t try to replace software documentation with code comments
I have come across terrible examples of how not to write proper software documentation. One of the most improper ways is to put hundreds of comments lines at the module’s beginning describing the entire application “architecture” (or any other documentation). I am not kidding you, and this was a real case. There is so much wrong with that that I even do not have the power to explain. Just don’t do it!
Don’t leave big blocks of commented code just in case you need them for later
With the current state of technologies, this is just not needed. If you do not use some version control system like GIT in your project, you have a bigger problem than the quality of code comments.
Don’t use comments for separators
If you find yourself writing things like:
// Here, we start checking for missing products.
...
...
... And then 15 lines below:
// Here, we start checking for products with limited availability.
This type of comment is a code smell—a big one. We do not use comments to separate code. We refactor our code into smaller, well-tailored code structures (modules, classes, methods, etc. )
Should I even bother with writing code comments?
Of-course! We don’t even need to comment on it (pun intended).
But comments should be meaningful and only where necessary. The problem is that it is hard to know where it is that necessary.
Here are some good practices you can follow:
- The comment you write should explain “why” something is done, but not “how”;
- If you are not sure a comment is needed, don’t write it;
- Comment only the general idea of the different parts behind complex algorithms;
- If your code looks stupid, but there is a reason behind this – write a comment. Of course, in case you can not refactor it;
- If your code depends on something external with a potential strange behavior – write a comment.
- If your code has some not implemented paths of execution, comment about them;
- Leave a URL to the source if you use some external solution in your code (thank you, Stackoverflow!).
- Use short single-line comments instead of blocks. Most of the time, you are going to write something unnecessary in the comment block.
- Be disciplined. Don’t forget to edit the comment if the code is changed. Wrong comments are worse than no comments;
