Thursday, February 17. 2005
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:
See the example in the Pear manual for a demonstration of these principles. Next up: separating code from content.
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.
< Previous Entry | Next Entry >
Trackbacks
Practical PHP Coding Standards - Part 2 / 3
In Part One we examined PHPDocumentor -- a powerful tool to document your code, and some pointers on how to use DocBlocks. Now, the second directive is: Separate Code From Content. This means use a templating system. The most basic form of templating s
In Part One we examined PHPDocumentor -- a powerful tool to document your code, and some pointers on how to use DocBlocks. Now, the second directive is: Separate Code From Content. This means use a templating system. The most basic form of templating s
Weblog: Robert Peake
Tracked: Feb 18, 18:07
Tracked: Feb 18, 18:07
Reader Comments
Thea Swanson on "Road Sign on Interstate 5" Now Available Online
Thank you for writing this poem. It’s necessary. Peace+ Thea
(Read more...)
Katherine on What Marriage Means to Me
Beautiful. Thank you.
(Read more...)
michelle on "Road Sign on Interstate 5" Now Available Online
such a stunner. hey, you are good! xoxo, mich
(Read more...)