Comment — the good, bad and tautology of software documentation

The Comment in code? Good or Bad?

How do you feel about comments?

  • Love them?
  • Hate them?
  • Don’t believe them?

The truth is most people who write code are lazy documentors. They write bad comments, if indeed they write any at all, working on the misguided belief that their code is ‘self documenting’.

Time to wake up, smell the coffee and step off the dais.

Fact: your code is not self documenting. Sure, I can read what you’re doing and see how you’re doing it. That’s easy. It’s embedded in the syntax you’ve written. What’s not obvious is your intent…

  • What were you trying to achieve?
  • Why were you doing it?
  • Why were you doing it that way?

You know the answer to these questions because you designed and wrote the code. But what happens in a few year’s time when you need to implement a new feature? How does the new starter who now needs to maintain your code know what you were thinking when you wrote it?

Writing comments, good comments, is a skill that’s often ignored, frequently overlooked and almost always undervalued.

What makes a bad comment?

No comment

A complete absence of comments in your code is always a bad thing. No exception! As I’ve mentioned above, you may fully understand the code you’ve written but…

  • …what happens in a few year’s time when you need to add a new feature?
  • …how does the next guy know what you were trying to achieve?
  • …how does the code review know if you’ve fulfilled the requirement?

Comment Tautology

Comments like this add absolutely nothing to the reader’s understanding of your code.

// Increment our index by 1
index++;

If you’re writing code like this, you’re wasting your time. There’s simply no value in adding this type of comment, hence the phrase Comment Tautology

Close coupled comments

Comments that are too closely coupled to your code very often don’t add much to the reader’s understanding. They tend to document what you’re doing rather than why you’re doing it or what your intent was.

A second side effect is increasing the maintenance points of your code. Close coupled comments frequently need updating as the code changes or risk becoming invalid, misleading and ultimately useless.

Misleading and/or invalid comments…

…are a symptom of close coupled comments that weren’t updated to reflect changes in the code. As such, they’re potentially very dangerous. They undermine the credibility of the rest of the comments in the code and reinforce the lazy coder’s belief that code should be self documenting.

What makes a good comment?

Good comments support the code and help the reader to understand what it’s supposed to do. They capture your intent, they capture why you made the coding choices you did and how you avoided any problems and pitfalls.

In a nutshell, good comments convey information to the reader that helps him/her to understand your code and, if they’re well written, will remain true after bug fixes and updates.

For example, if I’ve got it right you should be able to understand what this function is meant to do, additional code that needs to be added and easily see which lines are self documenting and those that need further explanation.

//----------------------------------------------------------------------------------------
//
// On uninstall we first need to cancel everything, then remove the database tables we
// created during activation
function cb_uninstall() {
    // TODO: Cancel any scheduled events
    
    // Delete all the uploaded files
    $settings = get_option('cb_settings_source_file');
    if (!empty($settings)) {
        foreach($settings as $setting) {
            wp_delete_file( $setting['path'] );
        }
    }    
    
    if ( !is_multisite() ) {
        delete_option('cb_settings_twitter_info');
        delete_option('cb_settings_500px_info');
        delete_option('cb_settings_source_file');
        delete_option('cb_settings_weight');
        delete_option('cb_settings_interval');
        delete_option('cb_settings_control');
    }
    else {
        global $wpdb;
        $blog_ids = $wpdb->get_col( "SELECT blog_id FROM $wpdb->blogs" );
        $original_blog_id = get_current_blog_id();

Conclusion

I’ve lost count of the number of times I’ve heard a programmer say “code should be self commenting” — in a way, they’re correct; any coder worth their salt should be able to read and understand the code. What they might not get though is why it’s written that way or what the author is trying to achieve.

Good commenting enhances the readability of the code and increases the reader’s knowledge of both how and why you’ve implemented it. It’s not so verbose that every line is documented but does offer clarification where it’s needed. Especially if you’re pushing the boundaries of the language.

Remember, you may not need to maintain your code so give the next guy a fighting chance at understanding it. You’ll earn a lot more respect and kudos for your hard work over time.

Share your thoughts...