WordPress Theme Coding Standards

Below you will find the coding best practices and standards that the AppThemes development team uses. It’s a continuously evolving document and will improve over time.

First off, we never start a theme or plugin without having first setup a repository in a version control system. Subversion (SVN) is the most popular solution and is what wordpress.org uses. If you want a quick tutorial on how to use SVN, check out the WordPress Codex, “Using Subversion” article.

Why is SVN so important? It allows you to keep backups (revisions) of every individual file so you can easily rollback. You can also create versions (tags) and branches to keep track of everything. It also makes things much easier when you’ve got a distributed development team like we do so developers don’t clobber each others’ changes.

Theme Development Standards

Before beginning any theme development, it’s important to make sure your theme includes all the necessary templates, styles, functions, and other items. The WordPress Codex has a great page on these theme standards so we always start here.

We also recommend starting with an existing theme like the default WordPress one, TwentyEleven or a completely naked theme like Starkers. These are great base themes to begin with and speed up development time.

Conditional Statements

If Else

When writing if….else statements, always make sure to indent the code to be executed between each section. Also don’t use {} if you don’t need to. Note the spacing between the parentheses and after the “if”.

if ( condition ) 
    echo 'true'; // code to be executed if condition is true
else
    echo 'false'; // code to be executed if condition is false

Loops

Make sure to always use brackets {} (instead of : and endif;) when setting up loops. This makes it much easier to see what’s happening inside the code block. It can easily get messy when you have if statements and other logic within the loop.

// foreach loop
foreach ( $results as $key => $value ) {
    // do something here
}
 
//while loop
$i = 1;
while ( $i <= 5 ) {
    // do something here
}

Data Escaping & Sanitation

Making sure our themes are secure is top priority. All data input and output needs to be escaped and sanitized. Escape as late as possible, ideally right before it’s displayed on the screen. Here are the WordPress functions that should be wrapped around variables.

Escape any text that appears within html
esc_html( $text )

Example

echo '<h1>' . esc_html( 'Blog Posts', 'appthemes' ) . '</h1>';

Echo and escape any text that appears within html
esc_html_e( $text )

Example

<label for="nav-menu"><?php esc_html_e( 'Select Menu:', 'appthemes' ); ?></label>

Encode text for use inside a textarea element
esc_textarea( $text )

Example

<textarea rows="5" cols="5"><?php echo esc_textarea( $comment->comment_content ); ?></textarea>

Escape values that are html attributes
esc_attr( $text )

Example

<input type="submit" name="Submit" value="<?php esc_attr_e( 'Activate', 'appthemes' ) ?>" />

Echo and escape values that are html attributes
esc_attr_e( $text )

Example

<a href="http://www.appthemes.com" title="<?php esc_attr_e( 'Visit Site', 'appthemes' ) ?>"><?php esc_html_e( 'Visit Site', 'appthemes' ); ?></a>

Sanitize URLs
esc_url( $url )

Example

$img = '<img src="' . esc_url( admin_url( 'images/comment-grey-bubble.png' ) ) . '" />';

Escape javascript strings
esc_js( $text )

Example

<script type='text/javascript'>
/* <![CDATA[ */
var pwsL10n = {
 empty: "<?php echo esc_js( __( 'Strength indicator', 'appthemes' ) ); ?>",
 short: "<?php echo esc_js( __( 'Very weak', 'appthemes' ) ); ?>",
};
try{convertEntities(pwsL10n);}catch(e){};
/* ]]> */
</script>

See the WordPress Codex for more details and a list of all data validation functions.

Database Escaping

To prevent SQL injections into the database, you always want to wrap your sql statement with “$wpdb->prepare” This escapes the data so malicious users cannot compromise the server. This is probably one of the most overlooked security issues when it comes to plugin and theme developers.

Here’s an example of how you would use the built-in WordPress escape function:

$thepost = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE ID = 1" ) );
echo $thepost->post_title;

Post Types & Taxonomy Standards

Any time a custom post type or taxonomy is used, a CONSTANT needs to be defined in theme-functions.php. There should never be a hardcoded post type or taxonomy anywhere else in the code. This makes it easy for other developers or non-native English speakers to change.

It also needs to be setup to allow customers to override it. Adding the !defined check before the constant is defined will allow them to do this.

// defined in theme-functions.php
if (!defined('APP_POST_TYPE'))
    define('APP_POST_TYPE', 'ad_listing');
 
if (!defined('APP_TAX_CAT'))
    define('APP_TAX_CAT', 'ad_cat');
 
if (!defined('APP_TAX_TAG'))
    define('APP_TAX_TAG', 'ad_tag');
An example of when you'd call this constant is a page:
 
// get all custom taxonomy category terms
echo get_the_term_list($post->ID, APP_TAX_CAT, '', ', ', '');

Documentation & Code Comments

We all know that most developers hate writing documentation. We also know how annoying it is trying to reverse engineer a function that doesn’t have comments. Comment your code. Comment your code. Comment your code. It will help you the next time you come back and work on it and it’ll help others too.

Here’s an example of how you should write comments in your code. Notice the main description, variable declaration, and comment within the actual function. This format is recognized by some IDEs and it also makes automatically generating docs with software like phpDocumentor a snap.

/**
 * This is the description of the function.
 *
 * @global string $app_edition
 */
function appthemes_cool_function() {
    global $app_edition;
 
    // this will print out the $app_edition value
    echo $app_edition . ' is such a cool function!';
}

jQuery Code Standards

In order to use the default jQuery shortcut of $, we need to set the $ as an alias like such:

jQuery(document).ready(function($) {
    // $() enter your normal jQuery code here using $ instead of jQuery declaration each time
});

If you want the code to execute immediately (instead of waiting for the DOM ready event), then you can use this wrapper method instead:

(function($) {
    // $() enter your normal jQuery code here using $ instead of jQuery declaration each time
})(jQuery);

Localization Standards

All text throughout the theme files need to be wrapped in localization tags. The standard name we use is, appthemes.

// echo out the text on the page
<?php _e('Here is some text', 'appthemes') ?>
 
// return the text instead of echoing
<?php __('Here is some text', 'appthemes') ?>

Variable Placeholders

In some cases you will have variables within sentences. Instead of having to breakup the sentence and create multiple _e strings, you can use a couple of nifty php functions, sprintf() and printf() which allow variable placeholders. The difference between the two functions is that sprintf returns a string and printf() echos it on screen.

When you have just one variable within a text string you’ll want to substitute it was a placeholder. In this case it’s a digit so we’ll use the %d.

$count = 30;
printf( __( "There are a total of %d coupons available.", 'appthemes' ), $count );

This would output, “There are a total of 30 coupons available.”.

$sitename = 'Widgets';
printf( __( "Welcome to the %s website.", 'appthemes' ), $sitename );

This would output, “Welcome to the Widgets website.”.

Here’s an example of how to use two variables within a text string called argument swapping. Notice that the text string is wrapped in single quotes instead of double quotes. This is required otherwise it won’t work.

$post_id = 30;
$address  = '123 Main St';
printf( __( 'Your post id is: %1$s. Your address is: %2$s.', 'appthemes' ), $post_id, $address );

This will output, “Your post id is: 30. Your address is: 123 Main St.

Now what about those cases when you have plurals? The most common occurrence, is with the comments text in WordPress themes. Fortunately WordPress contains a special function _n to handle this. The function accepts four arguments: singular string text, plural string text, variable, and text domain.

printf( _n( "We deleted %d spam message.", "We deleted %d spam messages.", $count ), 'appthemes' );

For a full list of formats allowed, see the PHP sprintf manual. The most commonly used formats are %s and %d.

JavaScript

Text strings within Javascript also need to be translated but the above method won’t work. In this case, you’ll want to use a specifically designed WordPress function called wp_localize_script to handle these.

For example, we have two files called theme-scripts.js and functions.php. The text we want to translate using this function is in theme-scripts.js.

Here’s the line of code in the .js function we changed. It includes a special javascript variable called theme_scripts_loc.sendEmailTrue which we declared in cp_theme_scripts_localization php function. Since php executes before Javascript, the wp_localize_script will declare those variables in the head so the included theme-scripts.js file loaded afterwards can reference them later.

$('.comments').append('<p>' + theme_scripts_loc.sendEmailTrue + ': ' + val.recipient + '</p>');

Here’s the wp_localize_script function that we added to our functions.php file.

// localized text for the theme-scripts.js file
function cp_theme_scripts_localization() {
 
    wp_localize_script( 'theme-scripts', 'theme_scripts_loc', array(
	'sendEmailTrue' => __('This coupon was successfully shared with', 'appthemes'),
	'sendEmailFalse' => __('There was a problem sharing this coupon with', 'appthemes')
    ) );
 
}
add_filter( 'wp_print_scripts', 'cp_theme_scripts_localization' );

So the next time you have another text string within your Javascript file that you need to translate, just add it to the cp_theme_scripts_localization function and the new variable name to your .js file. Done.

Displaying Numbers & Dates

When echoing out numbers and dates to the screen, it’s important to wrap them with special WordPress functions. These functions are number_format_i18n and date_i18n. This ensures that the number and date gets correctly displayed based on the localization (native language format) of the site.

echo 'Total Customers Today:' . number_format_i18n( $customers_today );

Total Customers Today: 1,035

echo 'Member Since:' . date_i18n( get_option('date_format') );

Member Since: 3/16/2011

When saving dates in the database, the easiest way is to use the WordPress built-in function, current_time(). This automatically factors in the time offset of the current blog’s setting.

echo current_time('mysql');

2011-07-09 12:58:51

Testing & Debugging

Ensuring that our themes are properly tested before they are rolled out is crucial. While you are developing it is recommended to have the WordPress Debug mode turned on. This allows you to see and fix any PHP errors, notices, and/or warnings. To enable debug mode, enter the following constant declaration in your wp-config.php file.

define('WP_DEBUG', true);

We also recommend installing a couple of useful developer plugins (written and used by WordPress core contributors) to aide in debugging and optimization.

  • Debug Bar – Adds a debug menu to the admin bar that shows query, cache, and other helpful debugging information.
  • Debug Bar Console – Adds a PHP/MySQL console to the debug bar. Requires the debug bar plugin.
  • Log Deprecated Notices – Logs the usage of deprecated files, functions, and function arguments. Then offers the alternative if available and identifies where the deprecated functionality is being used. You’ll also need to add these constant declarations in your wp-config.php file for them to work properly.
define('WP_DEBUG_DISPLAY', false);
define('SAVEQUERIES', true);

You should now see a new button in the top right corner of your admin bar called “Debug”.

Theme Unit Testing

It’s important to unit test your entire theme before making it available to the public. Most theme developers fail to do this and it later comes back to bite them in the butt. Unit testing allows you run through a pre-defined list of items that need to be tested.

WordPress graciously provides the steps and data to import and test against. Read the instructions on the theme unit testing Codex page to get started.

Theme Check & Review

After going through the theme unit testing above, it’s time to run down the theme review checklist. This guide lists out everything that should be included in your theme. After you check off everything on that list, the next steps is to send your theme through the theme meat grinder. The Theme Check plugin is the perfect tool just for that. It searches your theme for things like deprecated functions, notices, missing functions/declarations, etc. A summary is then provided so you can go back and fix/tweak as needed.

Developers Toolbox

We’ve been around the block a few times and tested all sorts of developer tools. We prefer to use open-source products but always go with whatever works best. Below is a list of our most favorite software which we use on a daily basis:

PC

  • TortoiseSVN – Top SVN client for PC users. Built-in diff tool, compare tags, and generate patches with ease.
  • NetBeans – Fully-featured Java IDE written completely in Java, with many modules available, such as: debugger, form editor, object browser, CVS, emacs integration.
  • Notepad++ – Powerful yet light-weight source code editor with plugin support.

Mac

  • Cornerstone – By far the best subversion (SVN) app for Mac users
  • SCPlugin – Finder add-on which is almost equivalent to PCs TortoiseSVN
  • TextWrangler – Not completely sold on it but it fits the bill (free, fast, lightweight). Just wish it had a few things like tabs & better undo options.

Cloud Services

  • Lighthouse – Private or public issue tracking system. It’s what we use internally to log tickets for our themes.
  • Beanstalk – Private sub-version and Git hosting. It’s where all our themes and development work lives. Supports auto deployments. Integrates with Lighthouse, Basecamp, Zendesk, and more.
  • P2 Theme – A great team communication tool. It’s like having a Facebook wall for your company.

Other Resources

Your rating: none
Rating: 5 - 2 votes

Written by: on July 22, 2011. Last modified: August 18, 2011

Popular Marketplace Items

  • autoauto-thumbnail
    $39

    AutoResponder AutoRegistration

     (4)
    Automatically integrates WordPress registration with major autoresponders.
  • Authorize.Net Thumbnail
    $39

    Authorize.Net

     (3)
    Easily start accepting online payments via credit card and e-check.
  • screenshot
    $39

    Convert

     (2)
    A conversion focused responsive Clipper child theme with premium features.
  • pcp-featured
    $39

    Price Comparer

     (3)
    Jump start your Price Comparision site with products from Amazon, Commission Junction, and LinkShare.
  • GeoReg thumbnail
    $29

    GeoReg

     (10)
    Captures detailed geographic info with new user registrations.
  • 2Checkout Payment Gateway Plugin
    $39

    2Checkout

     (4)
    Accept up to eight payment methods, fifteen languages, & twenty six currencies.
  • adposter-blocker-thumbnail
    $9

    AdPoster Blocker

     (2)
    A simple but powerful plugin that blocks spammy new user regs and/or ads/jobs/posts.
  • stripe-plugin
    $39

    Stripe

     (4)
    Process credit cards safely and securely on your AppThemes website.
  • AppThemes Coupon Plugin
    $29

    AppThemes Coupons

     (8)
    An easy way to start offering coupons and promotions to your customers.
  • marine-marketplace-thumb
    $39

    Marine

     (1)
    A clean, modernĀ and fully responsive marine-based goods WooCommerce Theme.
  • balanced-payments-plugin-sm
    $39

    Balanced Payments

     (3)
    Accept credit cards and setup escrow payments.
  • featured
    $9

    QR Codes Widget

     (3)
    Add a widget with QR codes to your AppThemes site.
  • daddy-likes-190x130
    $19

    Daddy Like

     (10)
    A fast, lightweight, and elegant "like" system for comments, pages, posts, & activities.
  • StarStruck WordPress Plugin Thumbnail
    $19

    StarStruck

     (16)
    A fast, lightweight, and elegant star rating system for comments, pages, & posts.
  • critic-icon-2
    $39

    Critic

     (7)
    A professional review and rating system for WordPress.