Chapter 1 of Robert Martin’s Clean Code: A Handbook of Agile Software Craftsmanship has a pretty amusing opening:
“You are reading this book for two reasons. First, you are a programmer. Second, you want to be a better programmer. Good. We need better programmers.“
More do
There’s definitely one thing I know that I can do more often with my code, which is to keep in mind what the chapter refers to as the Boy Scout rule: “Leave the campground cleaner than we found it.” I’m often guilty of leaving way too many things commented out in my code “just in case.” I’m a bit of an information hoarder, and I don’t like to delete things. To be fair, I’m quite organized with my data, but sometimes it ends up taking up more space than I intended.
Many things that I write, I write alone, so I don’t upload those things to Github. However, doing this promotes my bad habit of leaving in large chunks of commented-out code. So, to help with this, I can simply utilize a version control system with a little more regularity.
What this also got me thinking about was “What’s the best way to use comments?” I found an article on the Stack Overflow blog that I think gives a good outline for newer programmers on how to think about comments. They have a set of rules that they go through, but they’re all pretty self-explanatory:
Rule 1: Comments should not duplicate the code.
Rule 2: Good comments do not excuse unclear code.
Rule 3: If you can’t write a clear comment, there may be a problem with the code.
Rule 4: Comments should dispel confusion, not cause it.
Rule 5: Explain unidiomatic code in comments.
Rule 6: Provide links to the original source of copied code.
Rule 7: Include links to external references where they will be most helpful.
Rule 8: Add comments when fixing bugs.
Rule 9: Use comments to mark incomplete implementations.
The article can be found here: https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/
Less do
One thing I should avoid is taking the easy way out with any of my loops or algorithms. I also have a habit of just doing something the way that I already know how, but this doesn’t mean it’s necessarily the best or most efficient way of doing that thing. Taking the time to do a bit of research on best practices or the optimal way of writing something is not just good for my code but good for expanding my knowledge of various coding methods as well.
Leave a Reply