Practical PHP Coding Standards – Part 1 / 3

I have been thinking a lot lately about PHP coding standards. I recently became intimately familiar with the Pear Coding Standards through developing hands-on in that style. The truth is that while many points seemed valuable, on the whole a lot of the “finer points” of the coding standards did not really seem like the kind of stuff that would necessarily make code more maintainable for teams. The truth is that some practices will pay off in spades toward making your code coder-friendly. Others are more of a nice touch.

In my upcoming article for International PHP Magazine, I plan to go into detail on the enterprise PHP coding standards I have employed and found useful in developing business-critical web applications. For now, I would like to sketch out the basics and show you how to make gains quickly with a few practical points:

• Use PHPDocumentor to document all functions and classes
• Separate Code From Content
• Separate Content From Layout

In this entry, we will briefly touch upon documentation. Extremists in the extreme programming camp might try to persuade you that coding well and coding in pairs means the code documents itself. The truth is, however, that not all developers want to dig through code to find out how it works–they just want to reapply it quickly to their own situation. This is especially true in the case of an API. Enter PHPDocumentor.
PHPDocumentor is a very valuable tool for creating developer documentation. All functions and classes should be documented using PHPDocumentor DocBlocks and should be tested to make sure that PHPDocumentor can generate documentation from this code without errors or warnings.

More important than just the tool used, the documentation must be written in a useful way. This means:

• Document all input variables, their type, and any ranges (e.g. an integer between 1 and 10)
• Document all output variable(s), and their type(s)
• Document any side effects (e.g. changing a global variable or class variable)
• Describe what the function does or what the class does
• (Optional) Give an example of how to use the function or class

See the example in the Pear manual for a demonstration of these principles. Next up: separating code from content.