Do your code comments suck? Avoid these 3 traps!

Do your code comments suck? Avoid these 3 Traps!

Hey friend,

As a software engineer, you regularly work on projects with lots of moving pieces. Even if your codebase is small, it grows and grows as features are piled on, and it’s difficult over time to keep track of these of everything that’s going on. Nobody likes working on code that’s confusing & lacking documentation, which is why we’re going to have a nice heart-to-heart on commenting code.

By commenting your code well, you can make a positive impact on the products you work on and earn the respect and gratitude of your teammates for writing software that's easy to read and maintain.

Unfortunately, even the best of us can fall into several traps with comments that make our code puzzling and frustrating to our colleagues (and even our future selves 🤦‍♂️)

Today I want to talk about 3 traps with respect to code comments and what you can do to avoid them. Let’s discuss!

Now before we jump in make sure to grab this free guide I put together. IT's 6 best practices and tips that will help you put the pedal to the floor on your productivity and code quality. Commenting code is only 1 of these tips, and the other 5 are powerful strategies you can employ that will supercharge your ability to write code faster and cleaner, so stick around until the end!]

Alright, let’s dive in

Trap #1 – Overly Commented

Yes. You can actually add too many comments, and not all comments are useful! Let me explain.

Some questions that can lurk in the back of our minds when we write code comments are:

• What is the intelligence level of the people who will read this code?
• How much should I explain what’s going on here?

Have you ever come across code that literally had a comment before every line of code that follows? While not always the case, that’s usually a sign of something funky.

Sometimes in an effort to be helpful, we can unintentionally overexplain ourselves in comments.

Code that is overly commented:

• Wastes the developer’s time by writing excessive comments instead of more code
• Wastes the reader’s time, forcing them to wade through unnecessary clutter in with the limited screen real estate they have
• Assumes the reader isn’t intelligent enough to make inferences about your intentions on a line-by-line basis
• Adds redundancy by repeating what is already explicitly written

Overly commented code might be better served in things like tutorials where the audience has a wide range of familiarity and expertise, and it makes sense to be as inclusive as possible.

Here are some general litmus tests for overly commented code:

[TOSS]

• Does the comment explain the how something is done? Toss it.
  • In the book “The Pragmatic Programmer”, Tip #13, the authors Andy and Dave mention “The code already shows how it is done, so commenting on this is redundant – and a violation of the DRY [Don’t Repeat Yourself] Principle”
• Does the comment explain the programming language? Toss it
  • Language syntax & features are easily Googleable, don’t waste your time teaching your reader when they might already know, or can easily find out.
• Does the comment explain how a 3rd party API works? Toss it
  • Again, this should be easily Googleable.
  • It is the owner of this API’s responsibility for documenting their stuff, not you!
  • If the API is undocumented, you may have bigger problems on your hands. Look for another API that will help you accomplish what you need.

[Keep]

If your comment:

• Explains why you did it this way
• Clarifies the goal and purpose
• Discusses tradeoffs
• Makes complex business rules easier to digest
• Contribute to the documentation of YOUR public APIs

Keep It! Those are great things to have in comments

Trap #2 – Dead Code

We’ve all had (or will have) the story that goes like this:

“I just wrote a bunch of experimental code to help me solve my problem. It was helpful, but then something broke, so I commented the code out so I can use it for reference later on. Alright! I was able to replace my experimental code with something more robust and works way better! Now… what to do with this old function—should I delete it? Better keep it around just in case we need it in the future.”

Although well-intentioned, this hoarding mentality or sense of insecurity leads us to leave stuff like this in our codebases, cluttering them up for generations to come. If someone is curious about how something may have worked in the past, use a version control system with a blame function that lets them see how the code evolved over time.

A similar trap to this is forgetting to keep old comments up to date.
Did you change something in the code that makes the previous comment no longer relevant? Imagine how frustrating and confusing it would be for someone to read a comment about code that it wasn’t even intended for.

Delete unused code, and keep old comments up to date and you won’t fall into the trap of leaving dead code and comments in your codebase.

Trap #3 – Uncommented/Undercommented

Some people might throw around phrases like, “My code is self-documented” as a nebulous umbrella term to justify why their code has no comments.

“Self-documented” code, or code that is written clearly, concisely, with descriptive variable names etc. is absolutely something to strive for! But it doesn’t mean that the rest of your team (or even your future self) will have the context to understand your code.

Objection! I’m the only one who works on this code, no one needs to understand it but me!

Most of the time, you’re NOT the only one who needs to understand that code. But, even if that were true, your memory is not perfect. I guarantee you are not going to remember why you made every decision about why you wrote some code in a certain way for every single line of code you’ve written. Do your future self a favor, comment your code!

Here’s an analogy:

Imagine an engineer in the field disarming unexploded ordinances and landmines. Every once in a while he comes across a device and has to come up with an unorthodox solution using his wealth of experience and intuition. Perhaps he can safely remove the device from the field, but more work is needed to fully and properly disarm it. He may or may not be the person to follow up on this work which is why he provides brief, concise, clear context for the problem he encountered, what steps he took to resolve the issue, and what remains to be done.

Likewise, software is riddled with metaphorical landmines. When you come across them, the responsible thing to do is provide useful information or context so the code stays understandable and maintainable—helping the next person who comes along avoid getting blown up by something they weren’t expecting.

Here are some tips for improving your code that is lacking in comments

1. Use comments for generating documentation
   • Languages like C# and Java have XML Docs, and JavaDoc style comments respectively that can decorate things like classes, interfaces, methods, fields, and properties.
   • Modern IDE’s will even help you auto-generate these comments with places for you to fill in relevant information about the constructs you’re documenting.
   • When you’re ready, there are tools that can scan your source code and generate nicely formatted documentation for you, and it’s even accessible inside the IDE.
   • Does every construct in your source code need a doc comment? Depends! Are you making a library for other people to use? Is this just a hobby project? Think about the audience and make a judgement call about whether you need a doc comment.
2. Explain why you wrote it this way
   • There might have been several ways to accomplish something, and you probably made a conscious evaluation of the alternatives and settled on your solution. Was it performance? Readability? Best practice? This is great context to provide!
3. Code Hacks
   • If you have to write a hack to get something to work, and it’s important enough to leave in the codebase, [please for the love of Mike], leave a note! Consider answering these questions:
   • What were you trying to accomplish?
   • Why this solution is a hack and how do you wish this could work better?
   • What alternatives did you try, and why won’t they work?
   • What was the thought process behind your solution
   • How might you encourage someone else to find a better solution?
   • Remember: strike the balance between providing lots of helpful context while being as concise as possible.
4. Complex or confusing code
   • If something about the algorithm makes it hard to understand what’s going on, then feel free to clue people in
   • You can also reference any relevant documentation or resources [you know, like a link to that Stack Overflow post you totally sniped the code snippet from]

Wrapping up

OK – we covered 3 common traps that engineers fall into when commenting code. I hope this has been helpful to you, and you feel empowered to write clean, well-documented code that you can be proud of, and earns you respect and appreciation from your team. As a thank you for readying, I want to give you my 6 Tips for Writing Excellent Software. This no-fluff quick start guide that will help get results immediately. Go to www.sonicscholar.com/6tips and I’ll send it right to your inbox so you always have it.

Action Items

1.  Identify which of the 3 traps you're most tempted to fall in
2. What is one thing you want to apply the next time you’re at the keyboard coding away. 

That's all for you now, I'll see you in another post soon. Happy coding (and commenting)!