The SitePoint PHP blog has a new post by Jacek Barecki talking about documenting your code and some suggestions for keeping this documentation useful.

Pretty much every PHP developer writes comments along with the actual code. But the language itself doesn’t impose any rules on how to do so. You just have to wrap them around some specific tags and then you can write any content you want. So what exactly should be put in the comment blocks to keep them useful? Which parts of the code should be documented and which shouldn’t? In this article I will present some important rules which may help you in keeping your PHP code well documented and understandable.

There's three suggestions included in the article, each with a bit of explanation and a few screenshots to illustrate:

• Write code that explains itself
• Keep the balance
• Remember about the doc blocks

The Zend Developer Zone has posted a new article today with three tips to help you make your code a little easier to understand (both by other coders and yourself down the road).

Producing code that clearly conveys a developer's intent is key to any well written application. That not only applies to PHP, but every programming language. Developers who emphasize the creation of legible code tend to create applications which are easier to both maintain and expand upon.

His tips include suggestions about keeping conditional logic clean, using "less PHP and more HTML" and to make the best possible use that you can out of sprintf "and friends".