Source code – let alone WordPress code comments – is one of those things that often divide developers:

  • Some developers believe that code should be the documentation
  • Some developers believe that we should document every single line
  • Other developers feel that only complicated areas of code should be documented

In my latest series on Envato, I discuss a case for WordPress code comments on both the server-side and the client side.

WordPress Code Comments

I published the series in two parts each of which cover the two different aspects of WordPress development: The server-side, that is, PHP, and the client-side, and that is HTML, CSS, and JavaScript.

The Server Side

In this article, I cover the following topics:

  • Why They Matter
  • PHPDoc
  • Templates
  • Functions
  • Lines and Breaks
  • Generating Documentation

And I give code examples and links to resources for each of the above.

The Client Side

In the follow-up article, I cover the following:

  • Markup
  • ID’s, Classes, and the permutations of each
  • JavaScript
  • Stylesheets
  • Preprocessors
  • Other Tools

I also give examples and link to other resources for each of the above.

Above all else, the series is meant to provide a case for writing WordPress Code Comments – it’s not forcing any type of convention.

I think that we can all benefit from one another commenting their code especially in the open source (or, more specifically, the WordPress) space.