All Code Needs Comments

Commenting Common Sense

I wouldn’t want to touch your dirty toilet seat, so why would I want to touch your dirty code? I’ve just finished reading an interesting article about code comments; The Goldren Rule of Comments. The author makes some good points and I particularly like his analogy of uncommented code being like a toilet seat that has been… sprinkled on.

I think the article makes a good argument that code should be commented, what I think is lacking is a decent discussion on what makes a good comment. I can litter (an appropriate phrase) my code with as many comments as you like, but that doesn’t necessarily improve the readability or the quality of the code. Given the SearchEngine stats that WordPress offers me I think that there’s a bunch of people out there looking for similar advice.

Commenting snobbery

This is what I want to talk about first, and I think it’s an extension of what the difference is between a Developer and a Programmer. From some of the articles I’ve read and some of the people I’ve encountered there appears to be a lot of comment-based snobbering in development circles. Some people make you feel (because they tell you as much) that if you’re commenting your code then you’re not a good ‘coder’. Or maybe the ‘really good coders’ don’t have time to comment their code, so if you comment your code that makes you a different kind of coder.

Some people come with a reputation, deserved or not, of being God’s Gift to Programming. And if that person doesn’t comment their code then comments must be a bad thing, right? No, wrong. Wrong wrong wrong. Perhaps I’m revealing a little bit of my personal psyche here, but I really hate being made to feel that something I do is wrong just because someone else said so. A long time ago I gave up giving into that kind of pressure, I can only recommend that anyone who knows what I’m talking about take a look at themselves and make their own decision to just stop putting up with it and be yourself.

But I digress.

Basically, there is nothing bad about good comments in your code. Code comments are needed when you’re working in a team. Whether that’s a large multi-national cross-site team or a small inhouse one. Comments add information (or at least they should, as we shall see). As a quick overview, why are comments useful?

Why something is being done

Code can never tell you the Why, only the What. If you are new to the team or have no background context to the problem or you just plain forgot, the Why gives you that vital insight.

Explain Simple Statements

I remember a piece university course work I did once. The actual details are a bit murky but the assignment objectives was to teach the use of programming Java sockets and some basic networking principles. It was essentially some kind of very basic network emulator thingy. Anyway, I didn’t get full marks on the assignment because the data packets I was transmitting (according to some protocol which I believe the lecturer made up) weren’t being recieved correctly. When I saw the solution I found that the lecturer was right-sifting every packet by 2 before transmission and that is what made the thing work. To this day, I still don’t know why that was done. It was only one line of code, I knew the What behind it, but the Why escaped me. A comment would have cleared away that confusion.

I know this one is an extension of the previous but the distinction is in the size and scope of what you’re explaining. Explaining why returning a null is preferable to throwing an exception is applicable more to the previous point. Explaining why you’re right-shifting by x bits is this one.

JavaDocs (or similar) Make Useful Reference Manuals

JavaDocs are one of the most under-used tools available to developers. They should be explaining the why in detail. They’re such a useful and standard type of reference manual I really don’t understand why they are so little used. Think about the last time you used Sun’s API documentation to find out the details of some method. Now think about the last time you needed to work out what someone elses code did. Wouldn’t it have been quicker and easier to view their JavaDocs rather than have to parse their code to get the meaning? Ask yourself another question, if they’d used a different implementation would you have inferred the same meaning, even if it was semantically identical?

Comment Driven Development

I was doing a code review for someone a few weeks ago. I told him that I was disappointed that he hadn’t commented, as in JavaDoc, his unit tests. I felt that he should have explained in his comments what the input was going to be and what output was expected. The person I was reviewing came back saying, “But the tests are so simple you can see those details in the code.” And you know what? He was right. His tests were all small and self contained, had I spent a bit more time on his review I would have been able to see that all the major scenarios were being tested. There was no need for him to put those comments into his unit test code. I was wrong and I retracted my comment.

But that incident has got me thinking. Unit tests test the public interface of a given class. JavaDocs describe the public interface of a given class; so can I coin the phrase “Comment Driven Development”? This should go hand in hand with Test Driven Development₁. Your business code Javadocs should include phrases like;

• If the input is negative than that is returned
• If this happens that that exception is thrown
• If this is not found, then that happens

That’s going to help many people many times over. It’s going to help the original author fully think through everything that their method is supposed to do. (JavaDoc-style comments should be given to private methods to, but that’s more open to debate). It’s going to help the original developer write their unit tests (or validate their unit test coverage). It’s going to help your code review panel validate the behaviour of your method – and the coverage of your unit tests. It’s going to help someone doing a debugging exercise to see if the problem could be in your method – at a glance. It’s going to help other developers identify if your method is approproate to their needs or not without having to digest a single line of code.₂

If your code needs comments then it needs refactoring

There’s a school of thought that if you need to comment something then you should really be thinking about refactoring. This is a pretty good rule of thumb, but it’s only pretty good and it’s only a rule of thumb. If you’re suffering from cyclomatic complexity and you need some comments to explain what’s going on then you really should be thinking about a redesign or a refactor. However, if your comments are saying “right shift to satisfy-some-business-rule” then that isn’t a reason to refactor. Yes, your variable names and your method names should be useful enough to work out what is going on, but they’re probably not going to explain why you’re throwing an exception rather than returning a null (or vice versa). Again, the key word here is “why”.

Code Headers – “Added null check”

Some people hate code headers. These people mostly complain about how they’re not necessary, they get in the way, they make the top of the code all messey. I’ve even been told that they “take to long to update”? That last one makes me worry about the typing skills of some developers programmers, but anyway. I maintain that code headers are an inportant part of the history of the code, and that’s important for all kinds of reasons like having to roll back changes, merge different versions together and easily find out who did what and why.

The biggest argument people try to hit me with is “but we put that stuff in the check in comments”; the only good thing you can get from comments like that is that at least people are using version control! Reality is usually very different. Take a look at your code repository now and view the comments for some file. Now can you honestly say that the developers on your team have been dilligently adding “Did such-and-such because…” comments? Okay, next question. How many of the check-in comments only dealt with a single file? Most repositories allow you to check in multiple files at a time, but they don’t enforce a separate comment for each file. So even if you load your check in comments with detailed and useful comments, how can someone know which comment applies to which file?

Code headers provide this information on a per file basis and that gives anyone trying to understand the decisions behind the class instant access to all the data on it. Commenting in this way is like “one of those things”; the stuff you write down might not seem very important to you but it might be just the piece of information someone else is looking for in the future.

So where do check in comments fit in?

So what about those check in comments then? I don’t agree with anyone checking in code without there first being a piece of work that prompted the code change. Be that a standard work ID that means “bug fix” or “code tidy-up”, every change should be tracked back to some kind of request for it. In an ‘agile world’, and I apologise for using such a term, that work ID is probably the ID of the story you’re working on. Because a developer will most often be checking in multiple files at a time that what they should be putting into their check in comments. Not the description/reason for the change, but why the change was made i.e. what prompted it. The description of the change belongs in the code header.

Code Comments – “Add 1 to myValue”

• “Do this for everything in the List”
• “If myTest is true then…”
• “Multiples myValue by 2″

There is a word for these kinds of comments. Since this is a polite and family-aware blog, let’s say that word is “stupid”. They don’t tell anyone anything that the code doesn’t. In fact they are so simple and so verbose that they actually get in the way of the code. Okay, so I admit that most comments get in the way of the code anyway, but having these kinds of inane chatter all over the place makes the code even harder to see and understand and that’s a Bad Thing.

So if they’re bad comments, what do good comments look like?

• “Returning null here because…”
• “This right-shift is because…”

Note these good comments all end in “because”, this goes back to my previous point about comments always being about the Why. I don’t think you need any other types of comments in your code. If you’re having to explain a complicated algorithm then you need to think about if you should be refactoring. If you’re using a famous algorithm that you think needs explaination then that belong in the method header, or better yet just provide a link to a website that explains it.

Repetitive Points A Summary Make

The Goldren Rule of Comments makes a good point that comments are important and should be included in the source. Hopefully I’ve made a good start in explaining what makes a good comment good. At a risk of repeating myself ad nauseum, comments should be explaining the Why (or Why Not), the code gives you the What.

₁Or “Test Driven Design”, depending on your alligence.
₂And unless you’re part Cylon, natural language is always going to be faster for you to understand that code however well written it is.