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

Not just witty comments in your code

Documentation is like sex. When it’s good, it’s very good. When it’s bad, it’s still better than nothing.

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/
Posted in