Code. Food. Politics. Religion. Tech. Not necessarily in that order.

Not just witty comments in your code

Documentation best practices for themes, plugins and APIs, Presentation at WordCamp Hamilton 2019


  • Documentation
    • Helps guide the end user around your plugin/theme/package/etc
    • Can be either a user guide or code reference
  • Comments
    • Help guide the developer (you or someone using your code) understand what they’re looking at
    • Aids in the automated creation of a code reference

Code Comments


  • For others to understand your code
    • Not everyone writes obvious code, though that’s the goal)
  • For YOU to understand your code
  • Ease of creating a code reference
    • Automated apps like phpDocumentor for large projects
  • To do lists for yourself (@TODO)
  • Being a good open source citizen


  • Some are on the fence on the usefulness of code comments
    • Writing comments, then updating them is time consuming.
    • Takes precious bandwidth (in the case of JS & CSS)
    • Why should you have to write your code twice? Once for computers and once for humans?

So when should I comment my code?


*possibly unpopular opinion


  • “Your code should be self explanatory.”
    • This is true, but sometimes for brevity and/or efficiency, it may not be
    • What may be clear to you may not be clear to others.
  • Use comments as a means to briefly explain:
    • The file, the class or function/method using a docblock
    • A code block using simple comment

Simple Comments

// This is a simple comment
/* So is this */


 * Classy method.
 * Does something with the data then returns other data.
 * @param array $data Data that’s expected
 * @return array This is the good stuff
public function classy($data) {


 * Illustrates line wrapping for long param/return descriptions.
 * @param {string} foo This is a param with a description too long to fit in
 *     one line.
 * @return {number} This returns something that has a description too long
 *     to fit in one line.

API Documentation

  • There are many tools to choose from
    • Apiary,, etc.
  • Be verbose
    • But not too verbose
    • Explain everything, sometimes twice
    • Give all possible use case errors
  • The documentation is never done
    • API docs should always be a “living” document
  • Developers don’t read, they skim
    • Keep it short
    • Call out important points
  • When documenting data structures
    • Use expected and returned data types (JSON, XML, etc.)
    • Give possible submission and return values
    • Leave no room for error

User Guides

  • Who is your audience?
    • End user: novice or expert?
    • Developer: Newb or l33t?
  • Use plain language
    • No jargon/uncommon language (git? What’s that)
  • KISS principle
    • No long paragraphs. Point form is better.
    • Give them what they need, nothing more
  • What problem does your project solve?
  • Step-by-step instructions for common use cases
    • Installation, maintenance tasks, etc
  • Frequently Asked Questions
  • How/where to get support
    • Knowledge base, issue tracker
  • Screenshots, screenshots, screenshots
    • Screenshots

Do unto others as you would have them do unto you.


Posted in