0
<ul><ul><li>PHP Developer Best Practices Burlington, VT PHP  UG </li></ul></ul><ul><ul><li>26 June 2008 </li></ul></ul>Mat...
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 ...
What we'll cover tonight Documentation
But we don't have time! <ul><li>You don't have time to code? </li></ul>
API Documentation is Easy <ul><li>Simply prepend PHP docblocks to your methods and classes; your IDE will often do it for ...
What can I document this way? <ul><li>Classes, methods, class properties... </li></ul><ul><li>Use annotation tags in sourc...
Docblocks can organize code <ul><li>Utilize @category, @package, @subpackage; phpDoc uses these to organize documentation....
Docblocks can organize code <ul><li>Utilize @todo to keep track of what still needs to be done! </li></ul>
Generate pretty API docs <ul><li>phpDocumentor:  http://phpdoc.org/ </li></ul><ul><li>Doxygen: http://www.stack.nl/~dimitr...
See?
Caveat <ul><li>Be careful what you say: </li></ul><ul><ul><li>Docblocks can go out of date. Be general, except when it com...
IDEs like DocBlocks, too! <ul><li>IDEs introspect DocBlocks to provide typehinting, return values, and method descriptions...
So does Zend Framework! <ul><li>Various Server classes utilize DocBlocks to provide hinting for parameter and return value...
End-User Documentation
Users like documentation, too <ul><li>End users like to know how to use your code and applications </li></ul><ul><li>Give ...
XML is not a four-letter word <ul><li>DocBook is the most common format for open source documentation </li></ul><ul><li>Do...
DocBook is easy
One possible rendition:
Summary <ul><li>Document your APIs as you code them </li></ul><ul><ul><li>Run phpDocumentor frequently to keep the API doc...
Upcoming SlideShare
Loading in...5
×

Best Practices: Documentation

4,014

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
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
4,014
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
104
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

Transcript of "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: http://phpdoc.org/ </li></ul><ul><li>Doxygen: http://www.stack.nl/~dimitri/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 PHP.net 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.

×