One of the points of discussion that often comes up among software developers is how to best organize code and files within a project.

Some frameworks enforce for you to follow an organization scheme – such as Rails which prizes “convention over configuration” – and then other foundations, like WordPress, have standards for certain things – like markup and PHP – but don’t have standards for other things.

For example, there’s no real standard on how to name your stylesheet or JavaScript directories. There’s no standard for where libraries should be kept, nor is there a standard for where preprocessed or pre-minified files should be kept.

Sure, most of us have opinions on this, and developers often spend a lot of time (perhaps more time than they’d like to admit) thinking about optimal ways to organize this information, whereas others are happy to dump things in a directory and as long as the project has some semblance of organization (even if it makes sense only to them), they’re good to go.

Granted, there are personality traits at play here, but I digress.

I’m of the former case where I prefer to try to make sure things are highly organized – perhaps to my own detriment – and I try to bring the idea of “convention over configuration” to work I do within plugins and themes.

And though I spend more time talking about plugins, general practices, and other topics here, there are a few guidelines that I’ve been following as it relates to WordPress theme development that I’ve used in both my own projects as well as contract work.

Organizing WordPress Theme Functions

Talking about how to best organize the files that make up a WordPress theme is a lengthy series unto itself, and it brings with it a level of subjectivity that’s not worth trying to discuss in a single post.

However, there have been a few things that I’ve begun to implement as it relates to functions.php and other related files that contribute to the core of a WordPress theme. I’ve been using them in a number of projects and I’ve found that it helps to provide some type of organization in a space where it’s really easy to lose track of where certain types of functions reside.

Separation by Function Type

In object-oriented programming, there’s this notion of separation of concerns (which I’ve discussed around templates and queries); however, I don’t see this used as much in the context of procedural programming.

Admittedly, I’ve done far less procedural programming in my career so I could be completely ignorant on the topic, but it seems that it’s a more widely accepted practice to have giant files with collections of functions that aren’t necessarily related.

In WordPress, this is often functions.php.

But there are certainly ways to keep the files separated and organized in such a way that’s they show a bit more cohesion than just dumping them into one big file.

Organizing Theme Functions

As with anything programming related, this has potential to change in the future; however, here’s the organization scheme that I’ve found most useful for organizing WordPress theme functions.

Mayer Theme Functions

Here’s an survey of how I’ve broken things down in Mayer. Obviously, this isn’t going to be one-to-one with every theme, but the principles still apply.

  • `functions.php`. This includes a constant for tracking the theme version, `require_once` statements to bring in any dependencies (listed below), then hooks that are directly related the theme features, stylesheets, JavaScript, and comment-related functionality.
  • `inc`. This is a directory that contains files that are imported via the call to `require_once` call in `functions.php`. It’s meant to hold files that contribute to the theme, but aren’t part of the core theme hooks.
  • `inc/helpers.php`. These are functions that are used throughout the theme’s template files to help make the code more readable, and to abstract some of the core WordPress logic out of template files.
  • `inc/class-theme-nav-walker.php`. This class provides formatting for custom navigation in a theme.
  • `inc/theme-customizer.php`. This file includes all of the functionality necessary to utilize the WordPress theme customizer.
  • `inc/wpcom.php`. If the theme is going to be released on, then this file includes functionality specific to that environment.

Again, this is but one example of how I’ve found things to be useful.

For what it’s worth, I generally have functions.php, and inc directory, a helpers.php file, and then the rest are determined based on the features of the theme.

There’s No Single Best Strategy

Ultimately, the idea behind all of this is to bring a bit of cohesion to a relatively unorganized space.

Regardless of the ways in which you build your projects, the ability to maintain them over a long period of time matters. Making sure that you’re organizing things in a logic, conventional, and consistent way and go a long way in helping to do that.

With that said, I’m always curious for how others have gone about organizing their files, so if you’ve got an alternative way to do it, or something to add to the scheme above, then I’m all ears.

Otherwise, hopefully this helps with those of you looking to bring some way to wrangled your theme files into submission.