Thoughts on Code Commenting
One of the "behind the scenes" ways of organizing your code and making it maintainable is code commenting. Whether you're coding in Java, CSS, JavaScript, PHP, or any language for that matter, code commenting plays an important role in making your development life easy. I thought I'd just share some off-the-cuff thoughts about code commenting.
- Don't leave to-do lists within your code comments, especially if you're delivering code to the client. You think you're going to remember to remove it...you wont. Even if the to-do's are above and beyond the spec, the client or developer that follows you have license to point at what you didn't get done.
- Swearing in comments is unprofessional but I would never go so far as to say that you shouldn't do so. If changing this line will break the ENTIRE FUCKING app, swear away. Hopefully it will scare someone away from doing something crazy.
- Use single-line comments whenever possible. I always preferred multi-line comments but when you truly do need to comment out 50 lines, you're stuck deleting a whole lot of multi-line comment endings.
- Do not over comment. No one wants to read a novel about how "numItems" represents the number of items.
- If you are over-commenting, you're probably naming your functions and variables poorly.
- Citing line numbers in your comments is not helpful, as they will very soon become wrong.
- Keep in mind that Google Code allows other developers to search your code, comments included.
- Develop a habit of formatting your code comments consistently. That will allow for easier search and replace functionality in the future.
- Take the time to find good colors for your comments in your text editor of choice -- it will help more than you know.
- Insulting other developers in your code? In office: hilarious. Outside of work: offensive.
Those are just a my initial thoughts about code commenting. Have some thoughts to add? Share them!
Hi David!
Goods points here. I’d like to mention the use of Javadoc-like comments (JSDoc, PhpDoc, etc…), aswell.
I like these conventions, because:
1. it ensures comment consistency
2. it allows to generate API documentation automatically
3. it is supported by modern IDEs, such as Eclipse (which I use)
I know Mootools use another style of commenting conventions, but I don’t really know much about it.
Steven C. McConnell in his classical work “Code Complete” write a lot about code commenting as well as about other programming issues usually considered as “minor”, especially by newbies.
I see a good point in what you say in this article. However, I disagree with you in the path related to @todo lists. Personally, I see a good point in having reminders about the most “bleeding” issues right here, in the code. By the way, modern IDEs may generate @todo reports on the whole projects (or just on a part of a project) and you may switch to that very line from those reports! However, I usually do not deliver code to clients… May be that is the real point behind your words.
I would also llike to add my bit of advice. In case you use JSDoc, PhpDoc, etc to document your function/method signatures – oh please DO CHANGE the @docs when you change the signature!
Victor brings up a good point. I use @TODO a lot, especially since (nearly) all eclipse-based IDEs generate a todo list that allows you to easily go back through those before any delivery is made.
I sometimes use the todo lists in testing, say, for example, I change an email to one of my own for testing purposes, and have to comment out the customer’s, you can easily put a todo comment right above it, reminding yourself to change that back!
As for swearing, if it isn’t in the front-end code, I say fuck it. ;-)
I think a general rule of thumb for commenting should be:
The lesser the complexity, the less need for commenting.
The greater the complexity, the greater the need for commenting.
Just to sum up when and when it should not be used, since knowing when not to use comments is vital.
And, also, do not forget: when you’re going to write a comment – write a method instead! Self-explaining method/function/variable names are a must.
Not only do IDE’s detect @todo’s, our Hudson CI is set up to find all @todo, @deprecated, @fixme etc tags, list them by importance, and fails the build if there’s too many of them.
As for commenting code blocks with multiline comments:
if(0)
{
/* multiline comment …
*/
someCode();
}
Changing the if(0) obviously turns the block back on.
Don’t comment code. Instead, write self-documenting code. It’s easy to do. Yet it requires discipline and English language skills. It’s just that simple.
If you can’t, though. No worries. In fact, thank you! Because I get paid a lot of money to rewrite heavily commented code.;)
Relying only on self-documenting code misses the point that the developer may not have properly implemented the logic.
Self-documenting code only describes what is, not what should be, and it doesn’t exclude documenting it as well. Self-documenting code compliments commenting, not replaces it.
– David Bullock
Well said, David.
Either could be wrong, or both. That’s why self-documenting code wins over code with comments. The code is the documentation.
There’s no reason you can’t write self documenting code, and provide additional documentation, if only for the use of PHPDoc or the like. You make the over-reaching assumption that you are the only one able to write self-documenting code.
Some of us are required to provide additional documentation for use by others on our teams, or future programmers that may later join a project. While I agree that self documenting code should be what all programmers strive for, that does not make it the end-all be-all standard, and it is naive to declare so.
Sure your code should self document what it is doing… that goes without saying, but sometimes it’s still useful to have the why explained.
My rule of thumb is that you should never explain what you are doing that should always be obvious; if its not clean the code, but sometimes why you are doing it isn’t obvious i.e business requirements etc.
I think it’s a bit stupid arguing over these semantics. The overall goal is to simplify complex pieces of code with the use of English comments that are not only useful to yourself in the future, but other programmers. Keep it simple and stupid. ;)
I forgot to mention: method names & unit tests are cool kinds of comments ;) (I’m not saying they should be the only kinds)
Haha I used to to work in As/400 and not a single item of this list was followed by previous programmers, wich, in most cases made the programs before I was coneived. Also there were many in portuguese :P You could argue the coding language didn’t help, but believeme that was complete lack of interest.
Yes, it really *is* a problem. Actually, two problems – foreign language & lack of interest.
Personally (I am russian, by the way), I had a convention with myself – comments are written in english. I had to change that: mostly, I work with russians and some of my colleagues are not that good in english. It is nonsense when you camrade spends minutes on a translation site just to understand what you’ve said in your comment.
Regarding lack of interest… Well, it seems that many programmers are not quite interested in what they’re doing… I think that’s ok: the more uninterested programmers – the more money paid to others /with a sad irony/. By the way, how many of those uninterested programmers have read this post? Zero.
Multiline comments can certainly cause problems but they are often easier to use when you’re just debugging and need to hide something temporarily. Syntax highlighting will help a bit there since you will probably see if there’s something like */ inside a string that messes up the code.
I mostly just use a commenting plugin (NERDcommenter.vim for Vim) that takes care of the manual labor so using single line comments is as easy as selecting the code and commanding the plugin to toggle comments.
I think it’s fascinating: I stated coding in FORTRAN-IV and COBOL in 1980 and the arguments regarding if code should be commented (especially COBOL) had already begun.
We don’t seem to have made any progress.
COBOL coud have been self-documenting, but programmers liked to say IF FOO then BAR else X and who knew what FOO, BAR and X represented?
And then there were the ones coding in any language who liked being clever. Them, I feared the most.
I managed a group containing clever programmers once – including a Rocket Scientist (las in “it doesn’t take a rocket scientist to …”). She came from Russia and was, in fact a rocket scientist and I gave her the task of documenting a clever programmer’s code (whom I’d asked to leave).
She glanced at it and told me it was fine and completely understandable.
I asked her to spend a week on it and if she still felt that way, she could go onto something else.
That Friday, she came to me in amazement: there were recursing loops you couldn’t exit from – but that was OK because you couldn’t get into the, either. There were undefaulted conditionals and variables oddly named for no reason she could figure out. She thought the whole program should be thrown out and, if needed, rewritten.
I happened to agree with her and, getting back to the documentation, I said to her “It looked OK on the surface, but at some point, you realized it wasn’t. That was the point. You can’t document what you don’t understand.”
When a programmer’s done something clever and doesn’t explain why he did it and how it works; my assumption – based upon experience – is that he really doesn’t understand what he did sufficiently to explain it to anyone else – including a skilled peer. At that point, I reject the clever code and ask for the long version.