I've always loved Javadoc. It made it really easy to create documentation along with your code. While I'm a commenting freak (even when I'm in a huge rush I sometimes add comments while I work), I've found myself leaving out comments when I should have taken the time to add them. "I'll add comments later..." almost never happens. If you don't have the time to do it right the first time, why would you htink you'll find the time later?
So I've been wanting a Javadoc-style commenting/documentation system for PHP (which is what I've been 80% of my code in the last couple years). By lucky chance, I happened on PhpDoc. It parses comment blocks and creates documentation. Way cool. I think I'm going to start using it, see if I like it.
Thought I would add a comment to the "one almost never adds comments at at later date" idea of this post.
/* This comment is to remind me that I added a comment to this posting. What was I thinking?! I like to read comments but almost never add them. For a reason. It is a matter of job security, really. Those guys that add comments are suckers or not proletariat or both. Comments are mostly information and they serve to remove obfuscation which is the most powerful tool of the modern workplace. Remember this. And while you are at it remember that time you ate the shrimp at the Baja Bowl - God, you were sick for a week, you idiot, don't ever do that again; same goes for any form of gin or mixed drinks with that liquor added. */
Posted by T. at July 20, 2004 2:21 AM