The Big Debate: Should We Explain Code or Not?
Tags: python, java, javascript, career
Published: 2023-09-22 12:04:43


![Explaining Code: Yes or No?](https://images.pexels.com/photos/5900163/pexels-photo-5900163.jpeg?auto=compress&cs=tinysrgb&dpr=2&h=650&w=940)

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.

1. **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.

2. **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.

3. **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!