Stop Writing Comments

Ashley FriezeOctober 7th, 2019Last Updated: October 4th, 2019

1 121 2 minutes read

This should go without saying, but it doesn’t. We should treat a comment as though it’s a danger signal. A comment is either an admission of failure, or a warning about the unexpected.

In Talking Around Your Docs, I looked at how it used to be fashionable to explain every line of code.

I’ve also warned about Herp Derp and Cruft in Tests. All of which is about making what should be familiar things, long winded and overwrought.

Maybe if we defaulted comments to flashing red, people would use them more wisely!

Documentation is Good

API documentation, read inline with the code, and published out to API sites, is good! It’s versioned with the code; it’s right there; it explains the semantics around using that code. That’s got to be useful, right?

Absolutely!

What the HELL is THIS!?

//message bytes
byte[] messageBytes = getMessageBytes(theMessage);

The above is an example of a nervous tic. Filling a comment because we somehow need to sacrifice some screen space to the gods.

Would it be better like this?

// the message converted into bytes
byte[] messageBytes = getMessageBytes(theMessage);

No. Because the variable name should spell out what’s going on.

A lot of comments we write are no better than this!

When to write line by line comments

When I’m writing in an unfamiliar, or non human readable language, then I may choose to explain what the code is doing for the unwary.

This is probably in the category of an admission of failure. The truth is that I don’t really speak bash scripting, and my javascript is fine, but some of the constructs seem instantly forgettable:

return data.map(val => regex.match(val))
    .filter(x => x)
    .map(match => match[0])
    .filter(x => x)
    .filter(unique);

The above is valid code, but perhaps a little more obscure than the equivalent well-named methods in Java… and perhaps it would be overwrought to use explanatory functions, especially where the filter is concerned.

Can I be forgiven for:

// compare with path pattern
return data.map(val => regex.match(val))
    // remove non matches
    .filter(x => x)
 
    // convert to capturing group for customer
    .map(match => match[0])
 
    // remove falsy customers
    .filter(x => x)
 
    // use the unique algorithm to dedupe
    .filter(unique);

Maybe the above is helpful in terms of comment, but it’s no way to live your life.

Summary

Code is a language and should express itself. Sometimes our books have footnotes or asides in them to explain the text, and perhaps that’s useful occasionally in code. But it can’t be the norm.

In rare cases, it may be forgiven though… unless it’s saying nothing.

Published on Java Code Geeks with permission by Ashley Frieze, partner at our JCG program. See the original article here: Stop Writing Comments

Opinions expressed by Java Code Geeks contributors are their own.