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.
Nobody asked tabs vs. spaces? These people do not represent my interests. #debate
— Bill the Lizard (@lizardbill) October 17, 2012
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?