Working in the WordPress community is both a blessing and a curse. Because of its open source nature, we have a fantastic platform on which to build websites, themes, plugins, and even applications. It's got a smart community around it, rich documentation, and standards that aim to provide the way to write code for it and the way to build tools around it.

At the same time, the open source nature of WordPress as well as the languages with which it's built allow anyone to ship their work regardless of if it is up to any kind of standard or uses any kind of best practice. For many users, they're none-the-wiser about what's going on under the hood. If the product works, they're happy.

As people who are serious about their craft, we absolutely cannot settle for "just getting it to work." We have to care about what's under the hood.

If you're a serious WordPress developer, then you likely already have a method to how you work, but if you're just getting started or are looking to define yourself as a professional WordPress developer, then there are strategies, environments, and tools that you can utilize that can help.

In this three article series, we're going to look at exactly what those are and how they apply in our project work. First, we'll start with strategies.

File Organization

A significant part of building software is actually maintaining it after the initial launch. The truth is more time is actually spent in maintaining projects than building them. It makes sense, right? A product exists for far longer than it takes to create it, and, assuming that it's of high quality, then users are going to find bugs and request new features.

Unfortunately, a significant amount of maintenance time is spent on getting a bug resolved or quickly adding a new feature and is often done so in a way that is focused more on just getting it done than getting it done right. This isn't completely wrong either - when a product is tied directly to a business' bottom line, then time is a priority.

But there are things that can be done during initial development that can go a long way in making it easier to maintain a product after its launch.

For Themes

The WordPress Codex provides a comprehensive guide for how to build themes. It covers stylesheet guides, template files, JavaScript information, testing guidelines, checklists, and various references. Even if you're in the business of building themes, I highly recommend reviewing this list from time to time.

In addition to following the base set of guidelines, there are additional things that can be done to improve maintenance. Assuming that you're following the Codex guidelines for building themes, consider the following with regards to some of your assets and dependencies.

Assets

One of the things that I do for each one of my projects is make sure that I have specific directories for assets that are outside the normal files required for theme development. By this, I mean that I have specific directories for:

Images

Stylesheets

JavaScript

Language Files

Libraries, such as more modular code like plugins or PHP classes

...and so on

Granted, each theme requires at least a single stylesheet, but let's say that you're going to provide stylesheets specifically for the administrative dashboard. For maintenance, it's better to keep them separate than in a single stylesheet and then allow a tool to combine them before releasing them.

We'll be taking a look at tooling for exactly this in the final article in the series.

Regardless of where you land on this, doing a little bit of planning up front can go a long way to having a well-organized set of assets.

Naming Conventions

As we consider how to best organize our various assets, naming conventions can help provide a level of clarity and provide a standard by which all related files should follow. For example, in each of my projects I typically do the following:

Images related to a specific template are prefixed with the name of the template, for example: full-width.background.png

related to a specific template are prefixed with the name of the template, for example: JavaScript For the administrative dashboard, will be prefixed with admin and will be named depending on which the page they are loaded for: admin.edit-post.js , admin.users.js . For the theme, or the public-facing areas, will be prefixed with theme and named for the template on which they are loaded: theme.about.js .

Stylesheets are named like JavaScript Administrative-specific stylesheets are prefixed with admin and named depending on the page on which they're loaded: admin.widgets.css Theme-specific stylesheets are named in the same way in that they are named based on the template on which they are loaded: theme.about.css .

are named like JavaScript

Of course, there are some universal JavaScript and Stylesheets that are applied throughout the theme. In this case, I simply maintain a set of admin.css and style.css files.

For Plugins

Most WordPress developers know that plugins should be theme-agnostic. That is, they should not be dependent on a feature of any given theme nor should they impose any of their stylesheets or JavaScripts onto the existing theme except for their own specific feature.

On top of that, there are two ways to develop plugins:

To that end, there are a few strategies that can be employed when writing your plugins to make sure that the stylesheets, JavaScript, images, and other assets don't conflict with the existing theme.

Don't Mix and Match

When it comes to writing plugins, the various API's usually make it easy to mix and match the languages that you're using to build your plugin. By that, I mean that it's completely possible to include all styles, JavaScripts, HTML, and PHP in a single file and then ship it.

But I'm not a fan of this.

Typically, each language serves a specific purpose, and because of that, I try to keep each language in its own file as much as possible. Consider this:

HTML is used to describe the data that's rendered in the browser

CSS is used to style or present the data that's rendered in the browser

JavaScript is used to handle events and relay information to and from the browser and the server

PHP is meant to run on the server

As such, I believe that it makes more sense to keep the files separated so that you know where to focus when an issue arises or it's time to introduce a new feature.

This doesn't mean that you won't occasionally have PHP written in your markup or that you won't dynamically create HTML elements on the server side, but it's meant to provide a foundation off of which you organize your work.

Separation of Concerns

In addition to making sure that each set of stylesheets and JavaScript files are clearly named, I tend to follow the same structure that I do for themes and that is to name the administrative-specific code prefixed with admin and theme or public-specific code with display.

It's a simple strategy but it goes a long way in optimizing where you place your files and in maintaining issues as they present themselves once your work is in the wild.

A Final Word on Strategy

The point covering this is not to impose my way of organizing files into your system or even saying that this is a standard way of doing it. It's meant to provide a starting point for which you can maintain your projects.

Ultimately, the point is to minimize maintenance as much as possible. Having clearly defined naming conventions and a standard of organization allows you to know exactly how and where to place your files without doing any guesswork and it allows your collaborators and/or team members to know where to focus to track down issues as they arrive.

Reference Documents

One of the challenges that developers face is making sure that they are familiar with the proper ways to leverage the platform on which they're working.

For the most part, every language, framework, and library includes some form of documentation and WordPress is no different. The thing is, WordPress is composed of several different pieces - not only is the application built using PHP, but there are application-specific API's, as well as libraries such as jQuery that are necessary to have as references.

Because it takes a very long time to become intimately familiar with the ins and outs of each language, application, and library, professional WordPress developers usually have references readily available. For WordPress developers, the following references are extremely valuable.

PHP. Obviously, the language in which WordPress is written is valuable. Having the manual readily available for reviewing functions and classes is important especially if you're operating outside of the standard WordPress API.

Coding Standards. One of the biggest problems in WordPress development is that developers often don't apply coding standards to their work (I used to be guilty of this, too!). By following a standard, we're ensuring that all of our code will look the same and thus make it easier to contribute back to the community should we so desire. If nothing else, it makes for clean code.

WordPress API. This should be a no-brainer, but making sure that you're properly working with the various WordPress objects is necessary for professional development. Just because you can circumvent it doesn't mean you should. Odds are, if there's a method you need, it's already available as part of the core API.

jQuery API. jQuery is the JavaScript library that ships with WordPress and that is used for core functionality both inside the dashboard and inside many themes and plugins. It's best not to try to bring your own variant of JavaScript to the mix, but to stick with what's provided.

For the most part, that's it - bookmark those or have them readily available in your IDE (if it supports it), spend time in each of them, and you'll be well on your way to more professional development practices.

As far as strategies go, this covers it. Simply put, have a defined way to organize and name your files, make sure that you follow the best practices of the core WordPress API, and be sure to refer to the various language API documents when building your work, and you'll be in a far better position than simply building your work off the cuff.

In the next article, we'll take a look at various environments, version control, how they relate, and how they can be leveraged best in development, testing, and in final release.