Where Comments Are Useful

PHP In Action writes on the use of comments in code, specifically citing Eli White’s Commenting on Commenting over at PHP Advent. They are critical of Eli’s advice, saying that comments should be unnecessary, and that code should be clean enough to easily understand it.

There’s a lot of good advice, especially about writing clean code. But the article fails to address a good number of really critical details and to some degree misses the point of Eli’s article.

1. Writing comments beforehand can help articulate the why/how/what of an application. I’ve written comments many times that spell out the logic step by step. This invaluable process helps a developer think (and rethink) the business logic, and often refactor the code in ways that speed up its execution or development, before any code is actually written.
2. Descriptive, important comments make editing code easier. I’ve edited code where a big “Hey! Don’t Touch This!” would have been useful to me. Descriptive function names are helpful, but sometimes you can’t describe exactly what something does with a function name. Comments are helpful.
3. Getting in the habit of writing comments helps create to-do items. If you’re in the habit of writing comments already you’re more likely to leave a “todo” item behind so the next developer can clean something up. You’ll leave helpful notes on your thinking, and maybe even spark an idea for re-factoring, something that “descriptive code” can’t do.
4. Leaving good comments helps other members of your team understand your level of understanding, helping them help you improve those skills. Part of working on a team is improving each others skills and helping each other and a big part of that is knowing where each team member is. For the same reason that regular code check-ins and code review should be part of the development process, leaving notes that indicate where you struggled should be part of your process.

PHP in Action points out that writing good, self-descriptive code is important. I do not dispute that. Writing clear, concise code is important, and not filling in too many comments is critical. But self-documentation can only carry you so far; there has to be something else sometimes. That’s why PHP has comments at all.

Brandon Savage is the author of Mastering Object Oriented PHP and Practical Design Patterns in PHP

Joe Leblanc (@jlleblanc) wrote at 12/26/2008 10:06 pm:

I think that one of these days, I’m going to get a bumper sticker reading “not all code is poetry.” Self-descriptive code can help to a point, but if you’re doing client driven work, you’re eventually going to have to write something that works regardless of how it reads in the code. This is where comments are vital: when you have to describe a process that is not immediately obvious.

I also agree with Eli’s “write out the process step-by-step” advice. When you do this, you frequently find opportunities to create functions and classes to separate out your logic. Writing documentation has also helped me find bugs in functions (oh, I thought I was returning an array, etc…)

Copyright © 2023 by Brandon Savage. All rights reserved.