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.

As is mentioned in this Reddit post, two new PSRs have officially entered "Draft" status - PSR-5 for PHPDocumentor standards and PSR-6 related to caching implementations.

PSR-4 got to draft status a week ago and the other day it went into Review status. I pushed it to Review quickly as its already been around for several months (before this new workflow existed) so there didn't seem like much point in waiting. In less than two weeks we can put that in for an acceptance vote and we will have a new autoloader! Excellent. More good news from the FIG is that PSR-5 and PSR-6 are officially coming onto the scene, both now in Draft status too!

PSR-5, the PHPDoc standard, is more of an inclusion (and update) of most of the current standards people use when writing their PHPDoc comments, just more formalized by the PHP-FIG. PSR-6 is newer and is more akin to the logging PSR, defining the basic interface for an interchangeable caching layer. You can read more about each of the proposals in the mailing list: PSR-5: PHPDoc and PSR-6: caching.

On PHPMaster.com today there's a new post from Moshe Teutsch about working with docblock comments in PHP scripts and how to use the phpDocumentor tool to generate the documentation from them.

If you’ve ever tried to read code written by someone other than yourself (who hasn’t?), you know it can be a daunting task. [...] PhpDoc, short for PhpDocumentor, is a powerful tool that allows you to easily document your code via specially formatted comments. [...] By using PhpDoc, you can make it easy for others (and yourself) to understand your code - weeks, months, and even years after you’ve written it.

He introduces the concept of "docblocks" and includes several examples of how to comment things like packages, files, classes and functions/methods. Finally, he wraps up the post with an example of using the "phpdoc" command to run phpDocumentor and build the docs. In the comments, another tool is also suggested - DocBlox, a project that still parses the same docbloc syntax but does it in a much more memory efficient way (and is an actively maintained project).

On the Liip blog there's a new post that compares some of the popular PHPDocumentor-formatted comments parsers. They're looking specifically at the support for interfaces, not just the usual classes and methods.

The interfaces define the standard and are extensively documented. The implementation was built by copying the interfaces and implementing the methods. Now we have the documentation comments duplicated, which is a pain to maintain if we clarify or change anything in the interfaces documentation. [...] In PHP, there is a couple of doc compilers. While they basically all follow the same syntax as Java uses, none of them gets everything right unfortunately.

The four covered are PhpDoctor, DocBlox, PHPDoc and Doxygen. They look at things like namespace support, the inheritance information they generate and if it correctly uses the "@inheritDoc" tagging functionality.

Frederic Marand has pointed out a new subversion repository that's been set up for the documentation on the PHP-GTK project.

After recent complaints in the PHP-GTK mailing list, auroraeosrose mentioned mgdm has set up a SVN repository for the docs, to ease working on them. This new repository is available at http://svn.thefrozenfire.com/phpgtkdoc/

The trunk currently has repositories for the gtkdocs and the phpdoc application you can check out and use to generate and develop on the documentation locally.

On the Netbeans blog today, there's a new post that points to two articles about the IDE - one showing code completion in the Kohana framework and the other on completion in CodeIgniter.

How to achieve PHP code completion in Netbeans for the CodeIgniter, Kohana frameworks? See following articles:

Both articles come from the "My Beloved PHP" site:

• Netbeans: Code Completion for the Kohana Framework
• Netbeans revisited: Code Completion for Code-igniter - Part 1 & Part 2

In response to this previous post from Felix Geisendorfer, Sara Golemon shares a few thoughts on why she thinks it's just the other way around - create_function is not your friend.

In the short post she lists just a few of the issues surrounding the use of the function including that it:

• is prone to critical abuse by user-supplied code
• skips opcode cache optimizations
• encourages not using comments (evil)
• 100% blind to reflection or PHPDoc style documentation generation

In response to this previous post from Felix Geisendorfer, Sara Golemon shares a few thoughts on why she thinks it's just the other way around - create_function is not your friend.

In the short post she lists just a few of the issues surrounding the use of the function including that it:

• is prone to critical abuse by user-supplied code
• skips opcode cache optimizations
• encourages not using comments (evil)
• 100% blind to reflection or PHPDoc style documentation generation

Greg Beaver has a new post today on his blog concerning the interesting crossing paths of the phpDocumentor project and PEAR.

He notes that this improvement not only makes installing the phpDocumentor package more flexible, but it also makes it a snap to get up and running. Those used to the PEAR package system will be happy to know it's a simple "pear " command away. It makes full use of the package.xml 2.0 features to really make the install nice and clean.

Greg Beaver has a new post today on his blog concerning the interesting crossing paths of the phpDocumentor project and PEAR.

He notes that this improvement not only makes installing the phpDocumentor package more flexible, but it also makes it a snap to get up and running. Those used to the PEAR package system will be happy to know it's a simple "pear " command away. It makes full use of the package.xml 2.0 features to really make the install nice and clean.