Best Practices: Documentation


Published on

Third in a series of presentations on PHP Best Practices for the Burlington, VT PHP Users Group; this segment covers Documentation, both API and end-user.

Published in: Technology
  • Be the first to comment

No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Best Practices: Documentation

  1. 1. <ul><ul><li>PHP Developer Best Practices Burlington, VT PHP UG </li></ul></ul><ul><ul><li>26 June 2008 </li></ul></ul>Matthew Weier O'Phinney Software Architect Zend Technologies, Ltd.
  2. 2. About You <ul><li>Can you read your own code? Can others? </li></ul><ul><li>Is your software tested? </li></ul><ul><li>Is your software documented? </li></ul><ul><li>Are you using source control? </li></ul><ul><li>Does your team work efficiently? </li></ul><ul><li>Do you push buggy software into production? </li></ul><ul><li>Do you have a deployment plan? Does it include contingencies for rollbacks? </li></ul>
  3. 3. What we'll cover tonight Documentation
  4. 4. But we don't have time! <ul><li>You don't have time to code? </li></ul>
  5. 5. API Documentation is Easy <ul><li>Simply prepend PHP docblocks to your methods and classes; your IDE will often do it for you: </li></ul>
  6. 6. What can I document this way? <ul><li>Classes, methods, class properties... </li></ul><ul><li>Use annotation tags in source comments to provide context: @param, @return, @throws, @see, @todo </li></ul>
  7. 7. Docblocks can organize code <ul><li>Utilize @category, @package, @subpackage; phpDoc uses these to organize documentation. </li></ul><ul><li>Prefix your classes; easier to browse, and easier to mix with other libraries. </li></ul>
  8. 8. Docblocks can organize code <ul><li>Utilize @todo to keep track of what still needs to be done! </li></ul>
  9. 9. Generate pretty API docs <ul><li>phpDocumentor: </li></ul><ul><li>Doxygen: </li></ul>
  10. 10. See?
  11. 11. Caveat <ul><li>Be careful what you say: </li></ul><ul><ul><li>Docblocks can go out of date. Be general, except when it comes to the parameters and return values. </li></ul></ul><ul><ul><li>When in doubt, unit tests don't lie. </li></ul></ul>
  12. 12. IDEs like DocBlocks, too! <ul><li>IDEs introspect DocBlocks to provide typehinting, return values, and method descriptions. </li></ul>
  13. 13. So does Zend Framework! <ul><li>Various Server classes utilize DocBlocks to provide hinting for parameter and return value types, as well as method descriptions </li></ul><ul><ul><li>Zend_XmlRpc_Server </li></ul></ul><ul><ul><li>Zend_Rest_Server </li></ul></ul><ul><ul><li>Zend_Json_Server (coming soon!) </li></ul></ul><ul><ul><li>Zend_Soap_Wsdl (coming soon!) </li></ul></ul><ul><ul><li>Zend_Tool (coming soon!) </li></ul></ul>
  14. 14. End-User Documentation
  15. 15. Users like documentation, too <ul><li>End users like to know how to use your code and applications </li></ul><ul><li>Give them a manual! </li></ul>
  16. 16. XML is not a four-letter word <ul><li>DocBook is the most common format for open source documentation </li></ul><ul><li>DocBook can be compiled to a variety of formats: HTML, Windows Help files (CHM), PDF, and more. </li></ul><ul><li>Often used by book publishers (O'Reilly) </li></ul><ul><li>It powers the manual </li></ul><ul><li>It powers Zend Framework's manual </li></ul>
  17. 17. DocBook is easy
  18. 18. One possible rendition:
  19. 19. Summary <ul><li>Document your APIs as you code them </li></ul><ul><ul><li>Run phpDocumentor frequently to keep the API documentation up-to-date </li></ul></ul><ul><li>Write end-user documentation </li></ul><ul><ul><li>Use DocBook to allow for multiple formats </li></ul></ul>
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.