Sterling Hughes brings up an interesting point in one of his latest weblog entries when talking about comments in the source of PHP documents.

I think I must be the only person on the face of this earth, but I really hate source code comments. Here is why: They obstruct the control flow. I don't want 20 pages of comments inside the source code, They become outdated. Comment x was added in revision 1.1 of file y, and the developers didn't remove it, when it was obsoleted by revision 1.23 of file y, Comments rarely help me understand anything, and the generated documentation is really quite useless, unless you're out to specify an interface contract. So, what do I think should be the replacement for comments, and the solution to source code understanding? Read on...

His suggestion, as you go on to find out, is not just one method of making more effective comments, but four different ways/things that would be *much* more effective than just the normal PHP comments. Personally, I'd have to agree with him here. Code comments are nice, but they are just too easy to let go out of date. Then no one wins - the developers have no clue what anything does anymore, and the user viewing the code for the first time is lost as well...