Should There Be Developer Documentation for WordPress Themes?

For anyone who has been involved with building and/or supporting WordPress themes, then it can’t be understated how important documentation for WordPress themes can be for customers.

Generally speaking, this type of documentation refers to a manual that walks users through how to use a theme, it’s various features, and so on. I think it’s hard to argue that this is something that should be made available for everyone, or, at the very least, for those who have purchased the theme (of course, having a freely available manual can also serve as a marketing resource, but I digress).

But one thing that I don’t think talked about very often is if there should be developer documentation for WordPress themes.

Developer Documentation for WordPress Themes

When it comes to code comments, I’ve shared my opinion on this on multiple occasions:

In short, I’m a fan of commenting (sometimes to the point where I’ve been told it’s overkill). To be clear, code comments are not the type of documentation that I’m talking about.

Yes, they help clarify what the code is doing, they help you maintain your code in the future, and they help future developers know what each function, algorithm, or other block should be doing assuming throughout the course of its execution.

But when it comes to developer documentation for WordPress themes, I’m talking more about the idea of using PHP DocBlocks and tools such as phpDocumentor  to generate presentable, searchable, and easy to read documentation that doesn’t require developer hop into the code in order to figure out what’s going on within the theme.

The short answer is yes, I do think that there should be developer documentation for WordPress themes.

As with anything, this is not without its own objections, and two of the most popular ones I’ve heard are described below.

1. WordPress Themes Aren’t Software

Another way of looking at this is that software applications that provide some sort of API also provide developer documentation so that we know how to actually use it. As such, it makes sense for there to be developer documentation.

For many, WordPress themes are not software – and I fully understand that particular perspective – in fact, I used to hold to it myself; however, the more advanced your theme is, the more advanced work  (read: neat stuff) you may be doing within the theme.

And since WordPress leverages an event-driven design pattern, then it makes sense that at least some functions should have documentation included with it because it’s hooking into a larger foundation and it may be extending, overriding, or modifying core behavior.

Developers who are leveraging these themes for client work, or even their own project(s), need to be aware of how the theme may be doing something a little different than what a stock WordPress installation does.

If you don’t understand why something is happening, you may think the theme is broken or what something is up with WordPress, when in actuality, everything is working as expected – and the documentation describes it.

2. Inheritance (Or Child Themes)

Anyone who is experienced with object-oriented programming is familiar with the concept of inheritance, and although WordPress themes do not use objects when it comes to creating themes, it does introduce an inheritance mechanism that is not all together different from how it works in object-oriented programming.

In short, it works like this:

  • The parent theme – or the base theme – is like the base class. It provides styles, templates, JavaScript sources, or other elements that give functionality to the theme.
  • The child theme inherits everything from the base theme, but has the ability to override everything that’s mentioned above, as well as even call into functions that are defined within the base theme.

To that end, I’d argue that there’s a strong case for providing developer documentation for WordPress themes not only for those who are going to be working with the base theme itself, but especially for those who want to create child themes.

Practice What You Preach

I know – what weight do words carry if it’s not something I’m doing myself?

Right now, I’m only selling a single theme and I’m doing so on WordPress.com. This means that no one is really able to obtain the source code – at least not yet – in order to do any customizations or do any further development with it.

But that doesn’t mean I haven’t provided documentation for the theme:

Developer Documentation in WordPress Themes

I do this not only because I want to be able to understand what each function is doing as I maintain the theme, but I also want to be able to make sure that I have a foundation off of which others can build when I begin selling the theme for self-hosted blogs.

So yes, I’m an advocate for providing developer documentation for WordPress themes. If you aren’t going to do it for yourself, at least do it for those who will be purchasing your theme for a self-hosted installation.

It can go a long way in not only improving the maturity of your theme, but also in making your theme more accessible for those who are going to create their own customizations of it over time.

11 Replies to “Should There Be Developer Documentation for WordPress Themes?”

  1. I think anyone who thinks that writing a theme or even modifying a small piece of CSS is not writing code should think again. Chris Lema wrote a very good article on this which, annoyingly, I cannot find at the moment.

    Also, even if the source code for the theme is not available I think you still have to take account of the secondary audience which could be the developer him or her-self in 6 months time, and hence comment the code even if no-one else is going to look at it.

    1. I think anyone who thinks that writing a theme or even modifying a small piece of CSS is not writing code should think again.

      Yeah, and I can’t help but think that pre-processors for CSS have made this even more important. By that, I mean it helps to separate out files into logical components that not only support comments but can also identify that parts of the code that they are responsible for styling.

  2. Yes and Yes
    For customers the provision of a manual would improve the poor reputation that theme developers in general have for supporting their products.
    A developers manual should come as standard,costs being covered by a developers licence

    1. A developers manual should come as standard,costs being covered by a developers licence

      .

      I really like this idea. It’s super common sense, obviously, but for something so trivial, you don’t see this enough.

    1. We’d also like to see changelogs become common

      I 100% agree. This is something that I try to be really diligent about especially in my GitHub repositories (and I really owe @GaryJ props for making a huge point about that to me late last year).

      So there are those of us out there that are all for this, it’s just taking time to gain momentum or to be diligent in doing it :).

  3. I don’t think there should be a distinction between PHP written for a theme, PHP written for a plugin and PHP written for some non-WordPress environment. If it’s code, then document it.

    In the WP bubble, developers should be following the Inline Documentation standards – your screenshots suggests you’re doing otherwise.

    For instance, take http://make.wordpress.org/core/handbook/inline-documentation-standards/php-documentation-standards/#1-functions-and-class-methods – the order of tags is given with @since top, @return last, @param just before, and a few others and line breaks in between. Those three are probably the most important tags, so having them consistently positioned within a DocBlock across all WP-related code makes scanning that information easier.

    In (draft) PSR-5, the @subpackage tag is deprecated. Functions inherit @package tags from the file-level DocBlock, so @package really should be moved up there and not duplicated on each function.

    I’m not too keen on @version tags. They aren’t used in core, not in the WP documentation spec, and they are something which can lead to incorrect information. If you make a change in a function and forget to update the @version tag, then the “trustability” in your documentation has just dropped. Any change in @version is inherently ambiguous too – did you just change a comment, or fix a variable typo, or did you refactor the whole function? The only way to know would be to do a diff to the previous release anyway.

    Descriptions should be concise, particularly the Short Description. I’d change your first screenshot function to:

    Create a custom Read More link.

    Add columns to either side of the anchor to create a divider between the next post.

    The short description gives the minimum description of what it’s doing. Any extra information, like summarising how the link is being customised is left to the long description. There, use plain English (“Add”) instead of technical terms (“prepending”, “appending”) if possible.

    Brevity also helps for the second function description too:
    Add a class to a single post.
    Clear, singular (like giving an order, instead of “Adds”) and doesn’t mention the word “post” three times in 15 words.

    And yes, your non-documentation comments are overkill. Does any developer really need an “// end if” comment for a three-line conditional? Your insistence to comment the end of functions is also redundant, and from your screenshot, prone to inconsistency (one starts with “end”, one doesn’t). Again, core doesn’t use these by habit, and you’ve said yourself that for new code they are not really needed so why add bytes and visually clutter your code with them? :-)

  4. I use comment blocks to delimit sections of my code. This is because I use an old machine with a small screen when I code on the train. By putting the comment block in it makes it easier to see where I am in a class when paging up and down through it. Now I guess Tom does the same so he can see where he is. However I agree with Gary in that it is a bit overkill for a 3 line conditional. However for a much longer conditional this could be valid. Saying that of course if you need to mark the start and end of your conditionals or loops then maybe they are a) too long or b) too deeply nested?

    1. Now I guess Tom does the same so he can see where he is.

      This is true, and it’s something that I’m still not objected to doing because (and I’ve established this previous posts), I’d rather over-comment than not comment at all.

      That doesn’t mean there isn’t a balance to be struck, because there is, but it’s something that I — at this point in my career — am still working on :).

      Saying that of course if you need to mark the start and end of your conditionals or loops then maybe they are a) too long or b) too deeply nested?

      Yes — I actually have a post drafted about this, but it’s a habit I’ve had for a long time, and it’s something that I still think carries merit given different IDEs and my experience with reviewing others code (and others reviewing mine), but conditionals or loops that are too deeply nested are likely considered a code smell.

      Plus, there’s part of the whole software craftsmanship / SOLID principles that says functions should have a specific function. IIRC (and I may be way off with this), Bob Martin even expresses that good functions shouldn’t exceed 15 – 20 lines (comments excluded), so I definitely have room to improve in this particular area.

      I’m better that I was a couple of years ago, but I’m not where I want to be just yet.

      1. Other than habit, the need to feel like those comments should be there is definitely a code smell, even for working on a small screen.

        Bob Martin even expresses that good functions shouldn’t exceed 15 – 20 lines

        I’ve heard it to be even smaller – 4-8 lines being ideal. The actual numbers don’t matter so much (and it’s not always possible to get a function down that low – an array of more than a few elements sees to that) – but the clarity with which that function does a single task does. If the code can be self-documenting, then code comments should be minimal and the exception (to explain some abstract code) rather than the rule (your redundant end of block comments).

        1. Other than habit, the need to feel like those comments should be there is definitely a code smell, even for working on a small screen.

          Over time, I’ve honestly come around to agreeing with this — it’s one of those “bad habits are hard to break” types of things, but it’s also wrapped up in prior experience when working with other code bases.

          Dunno if it’ll matter or not, but I’ll likely do a follow-up post on this idea alone :).

          the clarity with which that function does a single task does.

          Agreed on all points.

          If the code can be self-documenting, then code comments should be minimal and the exception (to explain some abstract code) rather than the rule (your redundant end of block comments).

          Mostly agree with you here — the thing is, I’ve found “self-documenting code” to be something that’s also based on experience.

          By that, I mean that someone who is new to programming may likely have a harder time deciphering the code than someone who is more experienced. That’s just the nature of languages, I suppose (be it written/spoken, or programming).

          That said, I don’t think it’s unreasonable to assume that an intermediate-to-experienced WordPress developer who is familiar with PHP and the WordPress Coding Conventions would be able to pick up on what’s going on with the code.

          But that’s the problem — some times, I find people doing certain things against the coding conventions, or that introduce their own flavor of doing something (this includes myself, too! I’m not above admitting that I learn more about it each week :), but that’s where it really comes down to caring about what you’re developing on, I think, and that’s an entirely different topic so I digress.

          At any rate, it’s all good food for thought and, as usual, plenty of good stuff for me to think about moving forward. Lots of ideas and potential blog posts likely to come from this thread :).

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.