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

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