News Feed
Sections




News Archive
Looking for more information on how to do PHP the right way? Check out PHP: The Right Way

DZone.com:
Meaningless docblocks considered harmful
November 26, 2010 @ 08:43:32

On DZone.com today Giorgio Sironi warns against something that you might not have considered before but could still be harmful to you and your code - meaningless docblock content that could be confusing.

However, docblocks may become as evil as comments when they're not treated as first-class citizens. [...] Too often docblocks are generated and left there without any additional information. In other cases, they are filled mechanically with information that can already be inferred. In that case, you're not helping the programmers, which will have to maintain that docblock containing information duplicated from the method signature.

He offers a few hints to follow to make sure you stay out of the bad docblock trap - don't repeat the code definition, don't repeat the logic of the method, not using the <code> tag and using @throws correctly.

0 comments voice your opinion now!
docblock documentation code harmful opinion


blog comments powered by Disqus

Similar Posts

Reddit.com: Would you take a job where you had to use a custom MVC framework?

Jani Hartikainen's Blog: Common programming errors and how to avoid them

Jani Hartikainen's Blog: Zend Framework - good for beginners or not?

PHPClasses.org: Lately in PHP Podcast Episode 21 - Is PHP Source Quality Really Good?

Paul Reinheimer's Blog: Improving See Also


Community Events





Don't see your event here?
Let us know!


unittest podcast extension configure voicesoftheelephpant version series opinion install composer list laravel api release language interview introduction community symfony conference

All content copyright, 2015 PHPDeveloper.org :: info@phpdeveloper.org - Powered by the Solar PHP Framework