Why Clean Code Matters: Insights on Comments
Clean Code by Robert C. Martin
I recently finished reading Clean Code by Robert C. Martin, and I loved many points that I would implement in my approach to coding. Over the next few posts, I’ll share some key takeaways from the book, starting with a topic that’s often overlooked: comments.
While comments can be useful, they can also hide bad coding practices. Here are some Do’s and Don’ts for writing good comments, inspired by the book:
Don’t Explain Bad Code Comments don’t make up for bad code. If your code is hard to understand, fix the code instead of adding comments to explain it.
Don’t State the Obvious Comments like this are not helpful:
# Increment the counter
counter += 1
Don’t Use Comments as a Journal We often leave notes in the code about the author, reasons for changes, etc. Avoid doing this. Use version control tools like Git to track the history instead.
Don’t Leave Commented-Out Code Delete code you’re not using. Version control systems can always bring it back if needed.
Invest in Quality Well-thought-out comments save time for others and yourself. Don’t ramble; be brief but purposeful. If you want someone to invest their time in reading your comment, make it worth their effort.
Final Thoughts
Comments should help, not confuse. They are not a replacement for writing clean and clear code. Remember:
“Good code is its own best documentation.”
These are just a few takeaways from Clean Code about comments. I’ll share more in upcoming posts, including tips on writing better functions.
What’s your approach to writing comments? I’d love to hear your thoughts!
Fuel My Work
If you’ve found something here helpful, consider buying me a coffee (or helping me keep this server running)! ☕ Support me HERE
Need Guidance or Mentorship?
I’m happy to help! Whether it’s coding, career advice, or tech insights, feel free to reach out to me on Topmate: https://topmate.io/saxenaakansha30