News Feed
Sections




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

SoftLayer Blog:
Four Rules for Better Code Documentation
September 24, 2013 @ 12:07:56

On the SoftLayer blog today there's a new post with some recommendations for better code documentation - four tips to help make things clearer and cleaner.

Last month, Jeremy shared some valuable information regarding technical debt on SLDN. In his post, he discussed how omitting pertinent information when you're developing for a project can cause more work to build up in the future. One of the most common areas developers overlook when it comes to technical debt is documentation. This oversight comes in two forms: A complete omission of any documentation and inadequate information when documentation does exist. Simply documenting the functionality of your code is a great start, but the best way to close the information gap and avoid technical debt that stems from documentation (or lack thereof) is to follow four simple rules.

Their four recommendations cover several aspects of documentation:

  • Know Your Audience
  • Be Consistent - Terminology
  • Forget What You Know About Your Code...But Only Temporarily
  • Peer Review

They've also provided some examples of what they're talking about with PHPDocumentor-formatted comments.

0 comments voice your opinion now!
code documentation rules suggestion phpdocumentor phpdoc

Link: http://blog.softlayer.com/2013/four-rules-for-better-code-documentation

blog comments powered by Disqus

Similar Posts

SitePoint Web Blog: How Do You Work With Other People’s Code?

SitePoint PHP Blog: Visualize Your Code’s Quality with PhpMetrics

Jani Hartikainen's Blog: Is commenting your code useless?

NetTuts.com: How to Write Code That Embraces Change

Reddit.com: PSR-6 Caching Interface and PSR-5 PHPDoc enter Draft status


Community Events

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


introduction api performance laravel voicesoftheelephpant example library podcast php7 community application version series conference extension framework opinion interview release symfony2

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