« Seven Things | Searching Arrays for Values » |
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.
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
Posted on 12/24/2008 at 11:30 pm
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…)
« Seven Things | Searching Arrays for Values » |