I couldn’t possibly comment

While there is always some new tool or technique to learn in programming, there are other things where you think you’ve already got it sorted.  Commenting your code is one of those things for me.  When I read a recent article on comments, that asked if comments were good or bad, I thought “Obviously, they’re good”.

I’m glad I read it – I don’t agree with absolutely everything it says, but it did make me think about a topic that I hadn’t thought about for a very long time.

Actually, there are some bad comments:

1. Comments that are out of date and so lie or mislead you
2. Comments that waste time and space by merely restating the code as comments

Also, comments can be a sign (but aren’t always) that your code isn’t structured and named well enough to make sense.

However, the main thing I learned from the article was a rule of thumb that indicates a good comment: Does it include the word because?  A good comment will say why or why not.  Why did we do X?  Why didn’t we do Y?  These will actually help a programmer understand the code.

Such comments tend to have the word because in them – statement because reason.  Also, code – even things like SQL – will almost certainly not have the word because in, but might have the word as, which could be used as a synonym.  Because will show up only in comments and error or log messages, where it will probably indicate a message that will be equally good quality, for similar reasons.

So, I am developing the habit of checking for the word because when I write a comment.  If it doesn’t contain because, I think: why not?  Also, is there a because comment nearby?

The title comes from House of Cards – I was thinking of the original version, but it’s also in the US version.