Not just witty comments in your code

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

What?

• 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

Why?

• 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

When?

• 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?

ALWAYS.*

*possibly unpopular opinion

Where?

• “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 */
/* --- I STAND OUT A LITTLE MORE --- */

PHPDoc

/**
 * 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) {
    .
    .
    .
}

JSDoc

/**
 * 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, swagger.io, 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.

Sources

• https://dev.to/smoogie/i-ve-got-some-comment-for-you-3jid
• https://dev.to/realedwintorres/why-code-comments-still-matter-1el0
• https://visualstudiomagazine.com/articles/2013/07/26/why-commenting-code-is-still-bad.aspx
• https://docs.phpdoc.org/guides/docblocks.html
• https://docs.phpdoc.org/references/phpdoc/index.html
• https://devdocs.magento.com/guides/v2.3/coding-standards/docblock-standard-javascript.html
• https://www.userfocus.co.uk/articles/usermanuals.html
• https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
• https://pandurangpatil.docs.apiary.io/#
• https://docs.woocommerce.com/wc-apidocs/