Bad Code Comments and How to Avoid Them

I was fixing a bug in one of my plugins the other day and I found this code comment written by an (ex) developer of mine:

// Added safeguard to check for undefined functions for certain routines, that should facilitate graceful error handling.

I wondered what this really long comment was for, and what was so important that it needed that much explanation. Well, to my disappointment, it was for this if statement:

// Added safeguard to check for undefined functions for certain routines, that should facilitate graceful error handling.
if ( ! class_exists( 'MyClass' ) ) {
    class MyClass {
        // ...
    }
}

A simple class declaration…

I scrambled and quickly deleted that comment.

That if statement’s purpose is so obvious! The comment doesn’t bring any benefit to the code, there was no reason for it to exist and it just cluttered the screen.

I opened up my other projects and browsed the other comments. I discovered more committed comments that just made me scratch my head.

More Bad Comments

Here’re more code comments that I found. I swear that these are all real.

// EXTRA STAGE BONUS: Feature X now works again as well!

This was for some code that made an API work again (because it previously stopped working) – Trying to be too funny, it’s inappropriate, and triumphs aren’t supposed to be commented in the code in the first place. Deleted.

// Extra classes for faux element (prevents transform spasm)

The above was a comment on a CSS style being printed out – what the hell is a “faux element” and a “transform spasm”? There were no pseudo elements anywhere, so I had no clue what a “faux element” was in this case. Deleted.

// In case things go south, this is the last known backup that works
// (20-30 lines of commented out code)

This comment was for some old code that was commented out (but wasn’t removed) – This should have been deleted long ago along with the old non-working code since the new one was already working. This is why we have tools such as Git! Deleted along with the old code.

// Ensures drawing priority over other elements consistently across Feature X and Feature Y.
z-index: 999;

A comment about the higher z-index — I think this is unnecessary and is pretty self-explanatory. Removed.

// This should prevent template selection and prevent a template paradox.
add_action( 'init', array( ‘my_remove_page_attributes’ ) );
function my_remove_page_attributes() {
}

This is a comment for an empty function – this is another piece of magical code that somehow got committed. The code does nothing and more importantly, the comment makes it worse because I don’t know what the developer was thinking when he added this. What the hell is a “template paradox” anyway?!

I’m not saying that all my code comments are awesome though. Most likely I have a few bizarre ones too. But these comments that I found are just bad in my point of view.

What Are Good Comments?

Good comments are important. Without them, developers will lose tons of hours debugging.
Tweet

For me, comments are basically:

For explaining the why, what and how of a piece of code;
Should be easily understandable by other people (not just yourself); and
Should make sense now and in the future.

I try and follow these as much as possible because I know that I will benefit from my own comments in the long run. Good comments guarantee that I’ll understand a piece of code I wrote when I need to revisit it in the future.

Comments for Team Work & Collaborations

Comments are even more essential when you’re working with a team of developers.

Even when you don’t necessarily have to understand each and every single line of code another teammate wrote, there’s still a chance that you’ll be going through them sometime in a debugging session. And when that happens, those comments should help you out.

How to Write Comments

So how can you know whether the comment you’re writing is good or bad? Here’re a few personal pointers of what to do:

Document only the important stuff. No need to comment the obvious things.
Imagine yourself 2 years from now.. will you still understand what you wrote?
If another developer reads your comment, will it make sense?
Explain the why and how, don’t just convert the code you’re commenting into English
Make them simple, easy to understand, use easy words and don’t complicate things

Read your comment aloud and imagine someone else reading it. It should make you say “Ooohhhh I get it!”
Tweet

Conclusion

Think first before writing your code comment. Comments have a purpose!

Don’t write comments just because your lead developer says so or just for the sake of writing them.

Write them for yourself. And more importantly, write them for your future-self or for other people who might read your code.

Help your future-self know what you were thinking when you wrote that code so he can save half of his day debugging.

This is my First Blog Post

Hey, this is my first blog post! It’s a bit rant-ish, but it’s a start. If you enjoyed this or learned something, share it using the buttons below and follow me in Twitter @bfintal

Lastly, share your bad comments you’ve encountered below.