Best Practices: Documentation

  • 3,850 views
Uploaded 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.

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.

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
3,850
On Slideshare
0
From Embeds
0
Number of Embeds
1

Actions

Shares
Downloads
101
Comments
0
Likes
3

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

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