When building WordPress themes, there’s a rule that sits at the top of the list of rules. It’s something all developers should do out of habit, not as an afterthought.

Prefix everything.

What does it mean to prefix something? Basically, when you create custom functions, classes, and other items in the global namespace, it needs to be unique so that it doesn’t conflict with WordPress, plugins, or other scripts. Therefore, you add a prefix that’s unique to your theme name. If everyone follows this simple rule, it’s rare to see any conflicts. Like rare on the level of seeing a real-life unicorn.

Is it really a simple rule? Yes, and no. There are times to follow the rules and times to break the rules. There’s also a few extra things to cover, so follow along. While I’ll be focusing on themes, this applies directly to plugins as well.

What’s my prefix?

Fortunately, you have a prefix already made available to you, so all the guesswork about what prefix to use is already taken care of. This prefix is your theme slug. Take a look at the folder name you’ve packaged your theme in. That’s your prefix.

Let’s assume you have a theme named “Firefly” with a folder name of firefly. Your theme prefix is firefly_ or firefly-, depending on the circumstance. We’ll get to when to use an underscore or hyphen later.

Wait? What if my theme name has more than one word like “Firefly Browncoats”? That’s simple. You follow the same convention. Your slug becomes firefly_browncoats_ or firefly-browncoats-.

What should be prefixed?

Believe it or not, there are loads of things that need to be prefixed. Function names are the most obvious, but we’re not limited to those. Here’s a list of the most common things that should be prefixed:

• PHP function names.
• PHP class names.
• PHP global variables.
• Action/Filter hooks.
• Script handles.
• Style handles.
• Image size names.

Don’t assume this list is exhaustive. I’m sure there are things that I’m missing and new things will come in the future. These are just the common items in WordPress themes.

Also, while not technically prefixes, theme textdomains should also match the slug.

How to use prefixes

The simplest way to use a prefix is to add firefly_ (prefix we used above) to the beginning of whatever it is that you’re prefixing. So, if you had a function named do_something_cool(), you’d want to change that to firefly_do_someting_cool(). Sure, it makes the function name longer, but it also makes sure that the function doesn’t conflict with core WordPress, a plugin, or another PHP script running on a user’s site, which would create a nasty fatal error.

Depending on what you’re prefixing, you’ll need to know how to use that prefix. While there aren’t always hard-and-fast rules, if you follow core WordPress coding standards, things get pretty clear. The following is are examples of the various items that you should prefix.

Function names

function firefly_engine_failed()

Class names

class Firefly_Transport_Boat {}

Global variables

global $firefly_passengers;

Action hooks

do_action( ‘firefly_start_engine’ );

Filter hooks

$shutdown = apply_filters( ‘firefly_shutdown’, true );

Script handles

wp_enqueue_script( ‘firefly-vertical’, trailingslashit( get_theme_directory_uri() ) . ‘js/firefly-vertical.js’ );

Style handles

wp_enqueue_style( ‘firefly-paint-job’, trailingslashit( get_theme_directory_uri() ) . ‘css/firefly-paint-job.css’ );

Image size names (Note: Hyphens or underscores acceptable. Just be consistent.)

add_image_size( ‘firefly-large’, 1000, 500 );
add_image_size( ‘firefly_small’, 200, 200 );

When to break the rules

For every rule there’s an exception, right? Pretty much. There are times when it’s actually better to break the rules.

Pluggable functions immediately come to mind. I almost always advocate for not using pluggable functions for various reasons (we’ll save that discussion for another day). They exist, so we’ll talk about them. When building a child theme, it’s possible that the parent theme developer created some functions that can be overwritten in child themes. In that particular case, you must use the same function name to actually overwrite it.

Third-party script/style handles also offer a unique situation. See, if your theme loads the Genericons font stylesheet and another plugin does the same, you’d only want that file to load once. If both have unique handles, it’ll load twice. The best thing to do in this situation is to not prefix and simply use genericons in this case. Follow the core naming convention of lowercase letters and hyphenating between words in the handle.

Third-party PHP scripts/libraries are something I’d avoid prefixing as well. While it’s possible you could run a string replace in a text editor to add your prefix in, it’d be silly to do this every time you updated the library. Not to mention, if you’re using a version control system, you’re probably just pulling in those changes. In this particular scenario, your theme should do a function_exists() or class_exists() (whichever the case may be) before loading the third-party file.

I’m sure there are other exceptions as well, but these are the big three. Once you’ve learned the rules, it becomes a lot easier to recognize situations where you can or should break them.

A good rule of thumb to code by: When in doubt, prefix.