When I began my journey as a developer, I faced a problem. I couldn't understand some code because it seemed too complicated. I realized it wasn't just about my skill level; it had something to do with something people argue about a lot - explaining code with comments.
The Start: Why Comments Seemed Like a Lifesaver
At first, I thought comments were a blessing. They were like helpful signs on a confusing road, guiding me through the tricky parts of the code. After all, who wouldn't want help when things get tricky?
The Discovery: Comments vs. What Code Actually Does
As I got deeper into different code projects, I noticed something strange. Sometimes, the code and the comments didn't agree. The comments would say one thing, but the code would do something else. This made me more confused than I was before. I began to wonder if comments were as helpful as I thought. Was there a bigger problem here?
The Aha Moment: Code Should Speak for Itself
After wrestling with this code-comment mystery, I had a revelation. I found out that in the world of coding, there's a belief that code should be easy to understand on its own. It was then that I came across a big idea: "If you have to write a comment, it means you didn't write the code well enough."
The Argument for Easy-to-Understand Code
People who say "no comments" argue that code should be crystal clear, well-organized, and named in a way that anyone, even a newcomer, can understand it without needing extra comments. They think comments are like a band-aid that hides the real problem: messy, confusing code.
The Other Side: Why Comments Still Matter
But there are folks who believe comments are still important. They say comments have their place, especially when dealing with really complicated stuff or strange business rules. Comments can give extra info, context, or warnings that you can't see just by looking at the code.
Finding a Balance: Not Too Many, Not Too Few
So, what's the answer? Should we stop using comments entirely or fill our code with explanations? It's about finding a balance.
Make Your Code Easy to Understand: Try hard to write code that's simple to understand. Use names for things that make sense, break complex stuff into smaller, well-named parts, and follow the rules everyone agrees on.
Use Comments When Needed: If you use comments, make sure they really help. Use comments to explain why you did something a certain way or to give context that isn't obvious from the code itself. Don't use comments that just repeat what the code already says.
Keep Things Fresh: Check and improve your code regularly. Code that was once clear might get confusing as things change. Be ready to update your code and, if necessary, add or remove comments.
In Conclusion: Finding the Right Balance
In the debate about comments vs. no comments, there's no one-size-fits-all answer. Comments have their place, but they should support, not replace, well-written code. The main goal is to make your code as easy to understand as possible, with comments as extra help, not the main way to understand it.
In the end, my journey through this debate taught me that code should always be easy to read and work with. Whether you decide to use a lot of comments or very few, the most important thing is to write code that makes sense, so you and your fellow developers can work together smoothly.
What do you think about this ongoing debate? Share your thoughts and experiences in the comments below. Let's keep the conversation going!
Top comments (4)
I found this to be really important:
In short: Comments are not for what but for why.
Yes, I'm glad you pointed out the most important point when you want to use comment.
I completely agree. Code should inherently express its functionality and purpose. Comments should only be used when we can't make the code self-explanatory.
I would add, perhaps using Test Driven Development (TDD), we can avoid the common chaos that arises from quickly turning prototypes into proofs of concept or minimum viable products. This approach allows us to identify and address issues before they escalate, preventing the rush to production without sufficient refactoring or rewriting of the code base.
I completely understands what you trying to say and fully agree on your point, TDD should always be there no matter how small or big project you are working on, here I tried to explain one more advantage of TDD, check it out.
dev.to/kaushit/unveiling-the-magic...