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.

As is mentioned in this new post to the project's releases, Mike van Riel and the contributors to the phpDocumentor2 project have released version 2.0 - the first stable release!

We have spent the past two months fixing bugs, adding tests and writing a brand new template. With this release it is now easier than ever to generate your documentation. And as a special party gift we bring you a brand new template, called Clean. Can't wait to see what it looks like? Then come over and see the demo.

He talks about some of the things yet to come for phpDocumentor including more features based on the PHPDoc standard, improving performance and making the existing systems (and templates) more robust and usable. You can find the full roadmap here. phpDocumentor is one of the most widely used PHP-based tools for generating automated documentation from docblocks already in your code.

If you've ever looked at your code an wondered about its commenting, if there was a kind of "best practice" to follow when it comes to its structure, you should read this article from Andrew Podner about docblocks.

The subject is how to properly document code with PHP comments and docblocks. This one took a while for me to really just accept as a part of the development process. To me now, the comments are now just as much a part of the application as the code is. I believe it is that important. With IDE’s today, there really is no reason not to have good documentation in your source code.

He talks some about his own reluctance at first to use comments and how it helped him remember what his thought process was behind parts of this code. He includes an example of a typical docblock structure, showing the general description, parameters and a "return" value. He also includes something interesting in the topic of documentation - good variable names. There's links included to two tools that can take these standardized comments from your code and build HTML documentation from it - phpDocumentor and ApiGen.

You can find out more about the PHP docblock standards from this site.

Chris Hartjes, a big proponent of testing in the PHP community, has a new post to his blog about a new testing tool he's released to make it easier for you to know what needs testing - Tricorder.

I’ve hacked together a little CLI script that I think will be of use to many people who are trying to answer the question “just what should I do to test this thing anyway?” as they learn how to write PHPUnit tests to go along with their code. [...] I’ve created something that I am calling PHP-Tricorder, a CLI utility that can be used in conjunction with phpdoc structure.xml files to make suggestions on testing scenarios. It’s at a 0.1 release right now, so I anticipate it will grow and add more features as time goes on.

The post includes an example of the output generated from the phpdoc's XML output, recommending things like:

• Mocking certain objects
• Testing for data types and contents
• Recommending testing ideas for private/protected methods

You can grab (or contribute to!) the latest version of the tool over on github.

Gonzalo Ayuso has a new post to his blog looking at a method for injecting dependencies into your application's code based on comments in the PHPDocumentor-formatted comments of your methods.

Last month I attended to Codemotion conference. I was listening to a talk about Java and I saw the “@inject” decorator. I must admit I switched off my mind from the conference and I started to take notes in my notebook. The idea is to implement something similar in PHP. It’s a pity we don’t have real decorators in PHP. I really miss them. We need to use PhpDoc. It’s not the same than real decorators in other programming languages. That’s my prototype. Let’s go.

All of the code you'll need to recreate his solution is included - a sample "User" class that needs a valid PDO object in a private "db" property, a "DocInject" class that parses the comments and, using a new feature of PHP 5.4 (traits), injects the needed functionality into the "User" class and creates/assigns the object.

You can see just the full code in these two gists on Github.

As is mentioned in this new post to the DocBlox blog, there's been a major development between it and the phpDocumentor documentation generation tool - phpDocumentor 2 will be released soon, merging DocBlock and phpDocumentor into one tool!

Announcing phpDocumentor 2 – the merging of the old (phpDocumentor) and the new (DocBlox). With the first alpha release of phpDocumentor (2.0.0a1), the new “Responsive” default template sports a new page layout, along with the useful layout improvements that the original DocBlox templates provided (which remain available) over the old phpDocumentor templates (which will retire with old phpDocumentor). Explore this new template at http://demo.phpdoc.org/Responsive/index.html.

Users of the current phpDocumentor software (version 1.x) will need to upgrade their documentation and installations. If you'd like more information about the transition or just keep up with the latest on this exciting advancement, check out #phpdocumentor on Freenode IRC or follow @phpdocumentor on Twitter.

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 Tales of a Coder blog there's a recent post about DocBlox, an alternative to the usual phpDocumentor for generating automatic documentation, and how it made it "pain free" for her current project.

Want to generate documentation for your PHP project, but keep putting it off? Can't be bothered wading thigh deep in documentation, screaming WHY WON'T IT WORK as you try to set it up? Look no further. DocBlox is pain free and you'll be up and running, literally in a few minutes.

She includes a guide to getting the latest DocBlox installed and configured to work with your project. The configuration is a straight-forward XML file, so changing the settings to match your needs is easy (more on the config here). Once this is configured, building your documentation is one command away. For more details on DocBlox, check out the project's website.

As a follow up to his previous post about using DocBlock commenting and phpDocumentor for automatic project documentation generation, Michelangelo van Dam has posted a deeper look at DocBlox, one of his previously mentioned alternatives.

First of all, thank you all for the enormous feedback I got on my latest article on documentation of code. I got a lot of comments on the usage of PHPDocumentor. [...] I have to agree that [there are reasons] valid enough to step away from PHPDocumentor as a tool for documentation purposes and look for a better alternative. So I've investigated one tool most people have commented on or tweet-ed/facebook-ed/g+-ed on: DocBlox.

He touches on the installation of the tool and mentions this tutorial from Matthew Weier O'Phinney that guided him through the setup and use of DocBlox. He rand a few tests comparing phpDocumentor and DocBlox for the documentation generate and DocBlox came out on top when it came to runtime (and memory usage).