Find the Words to Match Your Code Poetry

Find the Words to Match Your Code Poetry

Do you follow standards for writing documentation? No? Well maybe it's about time you got started. Christine provides a few pointers on writing useful documentation for your code.

A few weeks ago, 200+ WordPress enthusiasts geeked out at WordCamp Vancouver and then attended the first ever BuddyCamp. For me, the highlight of the weekend was listening to John James Jacoby’s (AKA JJJ) presentation about proper documentation. His talk reminded me, that last year at WordCamp Toronto, Chip Bennett also gave a great presentation discussing documentation, and over in Montreal, Joey Kudish discussed the merits of becoming a better developer by writing better code. Weird how you need to hear the same thing three times to finally actually “hear it”. Well after WordCamp Vancouver, I finally started and I’m now documenting my themes properly.

I don’t know about you, but back in 2004 when I started working with WordPress, I didn’t pay much attention to standards, documentation, or the proper way to do things. But now, it seems as though the entire WordPress community is now working towards adopting the same standards.

This makes perfect sense and is quite easy to do and it’s so beneficial. You might not think that a WordPress theme needs much documentation or needs to adhere to a set of standards, but it’s actually quite easy to do, so why not give it a go?

Inline Documentation

Used extensively in the WordPress core code, inline documentation’s aim is to aid in future development and assist others when learning about PHP and WordPress. In his WordCamp presentation JJJ mentioned that it’s important to think of your future self. Years from now, you may look at a piece of code and may have no idea what it’s for. A WordPress theme rarely has that many files that run for hundreds and hundreds of lines, but adding file documentation using PHPdoc comment blocks gives it an overview on what the file is for, which is great for someone new stepping in and trying to figure things out.

The best way to learn about file documentation is to open a theme such at Twenty Ten, Twenty Eleven or Twenty Twelve. Since all these themes were created by the team at WordPress.org, you can be guaranteed that the file documentation follows standards as described in the Codex.

If you ever want to see amazing documentation, have a look at Chip Bennett’s theme Oenology.

Even the 404.php template has tons of useful bits of info. For a new theme developer, this theme is a goldmine.

<?php
/**
* Error 404 Page template file
*
* This file is the Error 404 Page template file, which is output whenever
* the server encounters a "404 - file not found" error.
*
* @uses oenology_hook_post_404() Defined in /functions/hooks.php
*
* @link http://codex.wordpress.org/Function_Reference/get_header get_header()
* @link http://codex.wordpress.org/Function_Reference/get_footer get_footer()
* @link http://codex.wordpress.org/Function_Reference/get_sidebar get_sidebar()
*
* @package Oenology
* @copyright Copyright (c) 2010, Chip Bennett
* @license http://www.gnu.org/licenses/old-licenses/gpl-2.0.html GNU General Public License, v2 (or newer)
*
* @since Oenology 1.0
*/
?>

Code Standards

Once again, with the goal of making code easier to read, understand and learn from, the WordPress team has put together a list of standards which they’ve shared on the Codex. Everything from single quotes rather than double quotes, indentation, brace style, naming conventions, etc… is fully documented and thus can be applied to your theme. Reading through this, you might disagree with some of the decisions made. One contentious topic is spaces vs. tabs. Unfortunately the entire programming community will always be in disagrement and it’s now reached mainstream ridicule, but WordPress has chosen tabs, so you’ll just have to deal with it.

CSS Standards

As a theme developer you’re bound to be spending the majority of your time editing and fiddling the CSS. Perhaps your stylesheet and your functions.php file will be the longest and both require great commenting and need to adhere to a set of standards. When designing websites, I was taught to lay out my Photoshop design in layers and logically position each as the webpage is. So for example my PSD may have the following layers:

  • Header
  • Navigation
  • Main content
  • Sidebar
  • Footer

I like to organize my CSS similarly and group sections together. My stylesheet may then be organize as such:

  • Reset
  • Global settings
  • Header
  • Navigation
  • Structure
  • Main Content
  • Sidebar
  • Footer
  • Comments

This kind of organization really keeps me sane during my design development and helps me find styles that need tweaking very easily. While working with Emil’s theme Responsive, I noticed that he also alphabetizes his elements which I had never thought to do before. So I’ve now started doing this as well and now get very irritated when I see it otherwise.

The team at Automattic responsible for making themes at WordPress.com follow a set of standards which they’ve shared in an extensive handbook which I encourage you to look at and bookmark.

Now, you might be thinking, I work alone and no-one looks at my code, so this doesn’t apply to me. But think of your future self or new developers who may look at your code and try to learn from it or even a future boss sneaking a peak at your code before he hires you. You’re code is something you should be proud of and let’s face it, wouldn’t it be great if all WordPress themes were developed with the same set of standards?

Comments

  1. says

    Thanks for the mention Christine, this is definitely good read and recommended for all involved with any type of development.

    Allow me to say hello to the team as well, it was very nice meeting everyone at the Summit.

    Emil

  2. says

    For folks who just want to dip their toes in the water and see if blogging is for them, I always recommend that they go to WordPress.com and sign up. The service is free and Automattic takes care of everything for you, so updates, spam, etc… It’s a great way to start blogging and see if it’s for you. Then when you have a budget and want to have full control of your site, you can just migrate away from .com and set up your own WordPress site at the hosting provider of your choice.

Leave a Reply