the well-bred grapefruit

@commondream and I had a brief discussion about the merits of comments.

I have a serious problem with the statement that “good code doesn’t need comments.” It seems to me that this is mostly used as a crutch for laziness - after all, I already know what the code does and why it does it, so it’s boring for me to go behind myself and write documentation for it. If I say that it’s good code, though, and that good code doesn’t need comments, then I spare myself of all that work!

Personally, I think comments are pretty much always useful. That’s not to say that comments should be ubiquitous, just that there is a time and place for them (and the fact that you might want to use some doesn’t mean your code is bad).

Good code is a lot like good writing, for a lot of reasons. The one that I want to focus on, though, is that good code knows its audience in the same way that good writing does - it makes reasonable assumptions about the people who will be reading it.

Examples: if I’m writing a bit of code that a bunch of beginners might look at - a Rails plugin, for example, is going to be seen by a bunch of people new to Rails, perhaps, if it becomes popular - I should keep that in mind when writing the code. In this example, I’ll probably comment the code pretty heavily to make it easy for a newbie to follow why the code does what it does.

On the other hand, if I’m writing some niche mathematics library that’s only ever going to be used by people who are already fairly familiar with the subject matter, I probably don’t need to explain why I’m having to cross-multiply the beta matrices; at the very least, I shouldn’t need to explain the basics of the operation.

In short, there’s no universally right answer for whether you should use comments on any particular part of your code, just like there’s no universally right answer on when you should use SAT words in your novel or make Battlestar Galactica references in your blog posts - it depends on your target audience.