{"id":499,"date":"2012-11-01T14:00:41","date_gmt":"2012-11-01T13:00:41","guid":{"rendered":"https:\/\/wprealm.com\/?p=499"},"modified":"2012-11-01T14:00:41","modified_gmt":"2012-11-01T13:00:41","slug":"code-is-poetry","status":"publish","type":"post","link":"http:\/\/wprealm.local\/code-is-poetry\/","title":{"rendered":"Find the Words to Match Your Code Poetry"},"content":{"rendered":"

A few weeks ago, 200+ WordPress enthusiasts geeked out at WordCamp Vancouver<\/a> and then attended the first ever BuddyCamp<\/a>. For me, the highlight of the weekend was listening to John James Jacoby’s (AKA JJJ) presentation about proper documentation<\/a>. 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<\/a> 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.<\/p>\n

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.<\/p>\n

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?<\/p>\n

Inline Documentation<\/h2>\n

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.<\/p>\n

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<\/a>.<\/p>\n

If you ever want to see amazing documentation, have a look at Chip Bennett’s theme Oenology<\/a>.<\/p>\n

Even the 404.php template has tons of useful bits of info. For a new theme developer, this theme is a goldmine.<\/p>\n

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

Code Standards<\/h2>\n

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<\/a>. 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.<\/p>\n

\n

Nobody asked tabs vs. spaces? These people do not represent my interests. #debate<\/a><\/p>\n

— Bill the Lizard (@lizardbill) October 17, 2012<\/a><\/p><\/blockquote>\n