The golden rule of comments

When I was in undergrad it seemed that all the professors were really anal about programming assignments being super commented. We always had to give each function a huge comment block header that described in detail what the function was all about, including sections on preconditions, postconditions and side effects. We were also expected to litter the code with single line comments to explain everything, I mean absolutely everything.

All of my assignments ended up having more comments than actual code. I starting thinking that this is how code is supposed to be.

Then I got my first job as a programmer, it was just a summer job while I was still in school. It was a small team of four, with me being the newbie. My first task involved writing a few simple classes. So, I did how I was taught, I wrote the code along with reams and reams of comments.

When the lead developer saw all my comments he got upset. I was shocked, isn’t that how it’s supposed to be done? He said all those comments were a big pain because if he wanted to change the code he would have to update the comments as well or else they would go out of sync. He said that my comments actually harmed maintainability.

So I asked him; don’t you think comments make code easier to understand? His reply; that you should write code that is so clean and readable that it doesn’t even need any comments to be understood. This shook me to the core (a bit melodramatic I know). Up until this point I was convinced that for code to be readable and maintainable it must be verbosely commented.

So I started writing code without comments just like the other developers. The code was clean and well formatted with descriptive variable and method names. Still, there were times when I had to read the other developers code and it wasn’t immediately clear to me what the code was all about. Even though the code was clean it still took time to dig through it to figure out what was really going on. Some comments would have helped.

Then I realized what was really going on. The lead developer had designed everything himself and had done the majority of the coding, he was also overseeing everyone else’s code contributions, that’s why he had no trouble understanding everything. The rest of us didn’t have that luxury.

Clean code is something ever programmer should strive for, but sometimes the only way to relay the true intent of the programmer is to put a little snippet of natural language inline with the code itself. I believe that the thoughts in a programmer’s head that exist while writing the code are just as important as the code itself.

At a previous job I would always stop coding about a half hour before leaving for the day so that I could comment all the code I had written that day. At my current job I just write comments as I code. The point is you have to write comments when your understanding of the code is still fresh in your mind. If you come back to write comments weeks after writing the code you will already have forgotten many of the details.

It bothers me when I have to dig through someone else’s code and there are absolutely no comments. No comments means there wasn’t any consideration that someone else would need to one day read that code.

I believe a good programmer should be perpetually aware as they are writing code that someday, somewhere, someone else will be reading that code, someone else will need to understand how that code works. A good programmer should strive to write understandable code.

Not commenting your code is like pissing on a toilet seat in a public washroom, the next guy who comes in is going to have to deal with that.

This leads to the golden rule of comments:

If you were reading someone else’s code you would want it to be commented, so… comment your code.

I’m not going saying anything about exactly how you should comment your code or how you should document your programs. I’m not talking about using javadoc or doxygen… use whatever you like. I’m not saying there should be reams of comments. If the code is truly simple enough that it doesn’t need comments then that’s a judgment call to be made. The only guideline I have is that code should be understandable.

Its just common programmer courtesy to try to make code understandable.

Comments?