Opinionated Perspective
Yes, Your Code Need Comments
And lots of them. So, stop boasting about how self-documenting your code is.
Code comments are an interesting topic that’s often subject to heavy debate, and programmers hold almost religious views on the matter. So, I thought, why not have a go at this one, as I do with the whole “not using if-else” and traditional branching.
Commenting on your code is like telling the same story twice. Except, one may get out of sync with reality and starts becoming a lie instead. Code should ideally be self-documenting and annotating it with // or # only increases the signal-to-noise ratio, for the worse.
That’s at least the mindset developers nowadays have converged on.
Many developers thoughtlessly spurt out things like “your code must be self-documenting,” “good code doesn’t need comments,” “commenting code is a bad idea,” or “comments are code-smells.” These are likely all versions of what you’ve been told throughout the years.
But let me tell you this little secret:
Using comments properly can vastly increase system and application comprehension.
Think about it this way, if you were only handed the DLLs to aspnet core or npm packages like React, would you be able to do anything with them, just by reading the class names and method declarations?
Probably not.
It’s completely okay to use comments — it’s even encouraged.
Code comments often make everyone’s life easier, including your future-self.
Sure, you need to name your classes, methods, variables, and so on mindfully but, there’s only so much context good names can capture. There’s a reason libraries are chosen over others, and many times it has something to do with how well the libraries are documented with standalone sites and comments.
Great comments convey a meaning that extends beyond what any class or method name ever could. Great comments tell me why a piece of code exists and how it’s properly used — perhaps even what’s out-of-scope for the…
