Overcommented code
I'm currently reading Joe Stump's three part series on a MVC-designed PHP framework, published at ONLamp.com. The article is well written but there is something I find very irritating about the presentation of the code samples: they're overcommented in the extreme! There are so many comments that it makes the code itself harder to comprehend. Really, is there any need to credit the code's author every 5 or 10 lines?! Otherwise, a good primer on MVC frameworks.
UPDATE: This is actually a four part series (though the third article is unformatted for some reason):
- Understanding MVC in PHP
- Implementing MVC in PHP: The Controller
- Implementing the View in PHP MVC
- Implementing MVC in PHP: The Model
April 22nd, 2006 at 8:25 pm
I've since switched to dropping my name into the file docblock and the class dockblock, but there *is* a reason for tagging each function with an @author tag. The company I work for has 3 full time programmers and, at various times, contractors working on the code. A single class might have 10 functions with each one programmed by someone else, hence the @author tag on each function.
Also the extreme amount of documentation was meant to be a part of the article and not necessarily my recommendations for commenting, though I'm a firm believer in phpDocumentor and documentation as a whole.
April 30th, 2006 at 2:24 pm
Thank you for taking the time to post a comment, Joe! Your reasoning makes perfect sense, and I too believe in good inline documentation/attribution. It seemed a little out of place to me in a public article series, but I certainly see the usefulness in a workplace setting. Thanks again for stopping by, and for the informative articles!