Tips for Better Code Comments

Okay, I’ll admit: comments are not an exciting topic for most programmers. They generally aren’t viewed by anyone else except other coders, and if we’re honest, most coders ignore them, either by folding them up in their IDE, or by skipping over them. This is normally because coders don’t think about their comments in the same way as they think about their code.

So here are the tips I’ve come across over time that have helped me make better use of comments.

1. Let the code comment itself

If your code is clear enough to understand, then you don’t need to add many comments, if any. This helps reduce background noise.

Consider: if a file has comments everywhere, you’ll ignore them. If, however, the code is simple, descriptive, and well formatted, with very few comments, you’re more likely to pay attention to them.

An important point to make, too, is that if you find yourself having to make more and more comments in your code, this is probably a code smell: something has gone wrong in your code, and you should consider refactoring it.

2. Make sure your comments add value

By value, I mean that it’s telling you something you need to know that the code doesn’t.

How often have you opened a file to find version history comments? Or commented out snippets of code with little messages like, “Saving this just in case we need it later”? Or a comment like, “I have no idea what this does”? Or the worst sin of all, a comment that’s just flat out incorrect?

Again, comments like these are just noise. Fix incorrect comments. Move version history out of your code into a separate file. Remove commented out code (if you really must keep it, save it into a separate file somewhere on your machine). If you have no idea what a piece of code does, spend some time understanding it and either refactor/rewrite your code so that it’s understandable, or leave a decent comment to help the next coder that comes along.

3. Keep your comments concise

People don’t like to read large blocks of comments just to understand something. Chances are, they’ll ignore it completely. You’re not writing an essay or dissertation. Say what you need to say in the shortest amount of words possible.

4. Stick to a standardized format for your comments

By standardizing the way you make your comments, you breed familiarity in the reader. They’ll know exactly where to look for crucial pieces of information, and visually will easily identify patterns to your comments. Tab your code, don’t be afraid to use new lines (especially before the comment), and use paragraphs. If you’re using something like PHP, PHPDocumentor can help in standardizing your comments, but make sure you don’t duplicate information that’s already told by your code.

5. Watch what you say

I said in the beginning that code and comments are only ever viewed by other coders. This is, of course, not always true. Consider Microsoft, whose Win2K source code got leaked onto the internet, and the computing world saw such comment gems as “we are such morons”, and “the f*cking alpha cpp compiler seems to f*ck up the goddam type “LPITEMIDLIST”" … well, you get the idea.

We like to have a good chuckle about these sorts of comments, but they could come back to haunt you. You never know who is going to read the comments in your code, so be polite, and keep it professional.

6. Comment now, not later

Don’t put off commenting until you’re finished; rather comment as you go along. It forces you to think about what you’re doing, which helps you become a better coder.

I also view it as a form of what’s called “technical debt“: just like when you go into debt with money, and you slowly have to pay more and more interest on those debts, in coding you fall into debt when you take shortcuts for short-term gains (e.g. you think the project can be finished quicker). You’ll pay for those debts over time.

Specifically, with comments, we rarely, if ever come back after a project to add them in, so your code will sit for some time until maybe you need to add new features, at which point you’ll look at your code, scratch your head, and try figure out what you were doing.

Further Reading

This entry was posted in Philosophy, PHP, Programming.

One Response to “Tips for Better Code Comments”

  1. [...] perchè, in fondo, sussiste sempre questa regola-suggerimento: “An important point to make, too, is that if you find yourself having to make more and more [...]

Leave a Reply