Commenting Code: Necessity or Redundancy?

How to comment your code

Do you think commenting code is necessary or a redundancy you'd be better off without?

Unfortunately, commenting code is still generally being debated by many. On one side are the proponents of the "code should be self-explanatory" standpoint while on the extreme other side of the pole are the (albeit rare) supporters of the "every line of code should be commented" rationale.

Personally, though, I believe that as with everything in software development, we have tools at our disposal that we can choose to use or not. When we do utilize the said tools and end up misusing them, however, we may very well cause mishaps.

Comments are there to offer better clarity to readers, our teammates, and our future selves... and sometimes, even to our IDE. As a matter of fact, I had a chat with Arcanys co-founder Fred Joye about this very topic in his podcast.

Click below to listen on Spotify or Apple Podcast.

If you wanna listen to more of Fred's podcast, check out his channel Smarter Software Outsourcing.

Now in case you'd rather read about my stand on this, let's first dive into the sea of coding truths, shall we?

Code is design

There’s a persistent saying over the internet that states "We should not write comment, we should write good code." And by "good code" we mean, of course, one that is self-explanatory. And this is true.

The code itself is the most complete documentation of the application. There is no better documentation because the code, by default, explains every aspect of the application, including the bugs.

Often, developers don't realize that they should write code as the application's documentation. They just think about how to make it work as soon as possible. Unfortunately, simply making it work is not enough.

So for starters, I think it's important to remember that the first documentation you have is your own code. This is why it is important that you make it clear, concise, and understandable. See your code as the documentation and it will change the way you write it. And when in doubt, you should try following the 8 Golden Principles when writing code.

As an example, instead of writing a comment, you can describe the complexity you want to document by creating a function with a good name. This is applicable for regex, long multi-line conditional statements, complex code, hacks and tricks (if you really need those), and ternary operators.

You do not code for yourself

The second thing to remember is that the owner of the code is not the developer, it is the team. So everyone should be able to understand it, especially for code review purposes.

And even if you work alone, keep in mind that you write code for others. Why? Because one day, your product might take off and it will most likely cost you an arm and a leg (or your company) to refactor your bad code because you can’t understand it yourself. So be kind to others, including your future self.

So yeah, sometimes, we need to set aside our personal preferences to lend clarity to our work. Even if we love those imbricated ternary operators, or we want to show off our deep understanding of regular expressions, we should stop using them so that our colleagues can actually understand our code and modify it, if necessary.

Then what?

Okay, done with the clean coding stuff. Let's talk about comments. Because, yes, they are still useful.

Sometimes it's not possible to document everything with code. It might be because we messed up in the first place and it is now too expensive to refactor, or because we lack time. But it can also be simply because the business processes are complicated and consequently, the code is complex as well.

Also, the code cannot explain the decisions we make. So it’s always a good idea to explain in comments why we added this or that condition, or why we wrote that specific line of code.

And even though I might sound old school here, I’m still pretty convinced that even after all the clean coding you do, it's still going to be faster and easier to read a sentence in plain English than a line of code.

As a general rule, remember that it's more expensive not to have enough comments than to have too much.

In consideration of our most junior developers

Clean coding is not something you learn the first day you write code. It takes years to master some principles, if you are conscious about them, and even after all those years of practice, you should still strive to improve your code every day.

Clean coding is also something we learn through (bad) experiences, which is something you don't have when you start. This is why you can’t expect junior, or even mid-level, developers to automatically write clean code.

Also, when we were young and innocent, we never wrote a single line of comment in our code because it sounded counterintuitive to spend time doing that. Or perhaps because we just didn't have enough brain power left to think about it at that moment, when we still had “that bug” to fix for yesterday.

Aside from that, there’s also the Dunning-Kruger effect, in which most junior and mid-level developers think they’re already Senior Architects. They think that commenting is for the newbies and that their code is perfectly understandable because they are already so good.

This can also be one of the reasons why you end up with terrible code, a project failure, and even a collapsing company. It’s because of people who are full of themselves.

When developers are concerned about quality and the consequences of writing good (or bad) code, then they will seriously think about their efficiency as well as the cost of their inefficiencies. And then, they will see the importance of writing comments.

And for all these reasons, when you have these people in your team, not teaching them to write good comments increases your technical debt.

OK. But in real life, Eric, how do YOU comment your code?

Personally, I like to add comments in my code because it eases my life so much when I get back to some old applications I wrote in the past. I hate it when I fail to comment some code, and I lose time understanding it again, which is why it has become a reflex for me to write comments in the first place.

Sometimes, I even implement what I call CDD (Comment Driven Development), especially when I have to write a complex algorithm. I like to first break it down into small parts, without worrying about the syntax. I write this in my comments and then "translate" those into whatever language I'm currently writing. When I finish, I clean up the useless ones.

And I try to always remember the following:

What do we want to comment?

Functions, methods, and class using DocBlock
Code that is not clear and easily understandable, and can’t be rewritten properly
Everything that we can’t explain with well-written code, such as the decisions we made

How do we write comment?

Single-line comments are written beginning with // (at least in C, Java, PHP, Javascript, etc...)
Multiple-line comments are written with / ** / (at least in C, Java, PHP, Javascript, etc...)
For functions, methods, and classes, we use DocBlock

More good practices

Never comment dead code. If the code is dead or not used anymore, delete it. Dead code pollutes the screen and decreases readability. For HTML, Javascript, and CSS, don't forget to remove comments with minification tools to reduce the size of your files and save bandwidth when your website is loaded.
Do not comment at the end of the line. This doesn't help create whitespace in the code and will just add more clutter. It will also be hard to delete the line without removing the comment and vice versa.

Some sources:

https://www.butterfly.com.au/blog/website-development/clean-high-quality-code-a-guide-on-how-to-become-a-better-programmer
https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/