Required WordPress Theme Files vs “Required”

The Required WordPress Theme Files

There are only 2 files that are actually required in a WordPress theme for it to be detected and applicable in WordPress. Those 2 files are style.css and index.php.

And then there are those “unsaid” files – those “secret” requirements that become the scuttlebutt amongst developers and are the difference between a good quality theme or “What noob built this thing?!”

So how far do you go? Aside from the required WordPress theme files, what files should actually be present in a theme regardless of whether they’re literally required and why? Well I’ve gone through a fair share of WordPress builds, and I’d like to share my thoughts on that.

Looks Matter.

Yeah, yeah, I know – it works! Whether you have 20 files or 3, if the theme serves it’s purpose, then who the hell cares what the dashboard or front-end looks like! The code is full of complexity and beautiful, damn it!

Just one problem with that… The same way people are less likely to buy a bruised apple when compared to a nice shiny one in a grocery store – and why we’re still having this debate over why Macs are more visually pleasing than PCs – the same way your theme is going to get judged. If someone looks at your theme and knows nothing about code or best practices or all the cool dingbats you added to WordPress that didn’t come out of the box – then they’re going to do what most of us do when we don’t have enough information to make proper judgement.

Judge by how it looks.

“If it ‘looks’ broken – it must be broken.” Yes – this is stupid, but I can’t tell you the number of time “bugs” were reported because a button overlapped something or an image was missing.

“OMG client, did you not see the super cool modal that has a slider in it?!”

Nope. Instead, the client noticed how many pixels off your sidebar was and called your theme a bruised apple. Looks matter.

So, how do we ensure that our theme doesn’t end up being the equivalent of a bruised apple? Here’s a few habits that I’ve gotten myself into doing – although they’re small things, they make a big difference:

1.  Always add a screenshot to your theme. It gives your client/user a preview of what they should expect and will be consistent with other WordPress themes on the Appearance/Theme page.
2. Keep and customize the style.css comments with your details. Perhaps if it’s a personal site, then “TwentyThirteenCopy” is fine and you can go foobar all the tags. But if this build is for a client, there’s nothing more off-putting than seeing copy and paste details just for the sake of making it show up on the dashboard. If you’ve put the effort into customizing the theme in all the other areas – then why not go that extra mile and name the theme after the client, provide your agency or your own name for the author site/urls, and once again – be consistent with other themes installed.
3. If you don’t need certain template files, then keep them out of the theme. However, don’t leave files in that are totally empty. Even if it’s the index.php, all of WordPress’ native index.php files have a comment in them: “Silence is golden”. Empty files give the impression that they must be there by mistake, at least a comment inside them will let others know it’s part of your theme.
4. Removing template files are fine, but future-proof! Know your theme’s purpose – if this is a blog, will the client ever need a category archive or comments? The last thing you want is to clear everything out before the client asks, “Oh, but where’s the comment form that comes with WordPress?” and “Why doesn’t the blogroll paginate anymore?”
5. Don’t forget the 404 page! This is the one template file that I always forgot to style in my earlier WordPress days until I caught on. Please integrate this with your theme’s styles and upgrade the default message to your needs. There’s nothing stranger than going to broken url and seeing that the 404 page itself appears just as broken. Oops.

Code Matters Too.

All right, so moving on from apples, the code quality does matter as well. Not only is it a reflection of yourself as a developer and your company, but it’s also a good form of future-proofing. How many times have you jumped into a theme of yours after not looking at it for months and have forgotten what the hell was going on in it? I don’t know about you – but it’s happened to me, so some cleanliness and documentation definitely help!

1. Functions.php VS a Plugin. I’ve seen this debate around and some are adamant about putting every custom function into a plugin whereas others are fine dropping their code in a functions.php file. I think the Codex breaks it down simple: If it’s custom to the theme itself and not something you’re using in other builds of yours – functions.php. If these are functions that may apply to other themes in the future – plugin. Besides, if you’re adding let’s say a new custom post type and that’s it – is it worth building an entire plugin just for that? Naaaah – overkill.
2. Comments! Please, please, please, do yourself and others a favor. Comment. What’s this function doing? What does this variable stand for? What is this template for? Who edited this block of code last? Where does this loop or div close? The worst thing as a developer is being thrown into a theme you’re inheriting from someone else, and finding that it’s all jibber jabber and no documentation. As if jumping into the unknown isn’t difficult as it is – be kind enough to leave a bread-trail. Thanks.
3. Stick to coding standards and be consistent. Check out WordPress’ coding standards if you haven’t had the chance. Perhaps it’s not necessary to stick to each and every single standard that’s set, but as a WordPress developer who honors the WordPress Philosopy, your code should be as readable as possible. In other words, don’t write a template file as if your tab key stopped working and the space-bar vanished. 🙂
4. If you’re making the content in a Content Management System hard to manage, you’re doing it wrong. The WordPress Philosopy says it best: You shouldn’t have to battle to use the standard functionality of WordPress. It can take some time to understand what WordPress is truly capable of – and I’ve seen devs just strip everything to write from scratch without realizing the time that could have been saved had they understood that capability. Research. Talk to others. Before you build out code, think of the UI on the dashboard. And perhaps keep this quote in mind as well:

There’s always time for cleanup.

Okay, I’m guilty of this. I work 40+ hours, have to buy groceries, do the laundry, decide what’s for dinner, walk the dog – what? Clean code? Last thing on my mind ever!

Buuut – there’s always time. Even if you “work 8 hours a day”, you’re not literally working 8 hours a day – or I hope not. Cleanup doesn’t have to be a long torturous chore. Like washing dishes (which I absolutely hate with a venomous passion). I use the one soapy sponge rule. Lather the sponge with soap and wash as many dishes as I can until that sponge is soap-less. Then come back to it, or if I’m on a roll, keep going!

Wait – we’re talking about code. Ahem, what I mean is you can take it in increments. Don’t feel pressured to clean and optimize every single part of your theme. Tackle it little by little or all at once – so long as it gets done. You’ll thank yourself later and feel happier – like a sink without dishes. Others will thank you too.

The Secret is Out!

And now we can all feel like professionals in this inner circle of WordPress know hows. Very quickly, let’s go over what we talked about.

• Only index.php and style.css are literally required.
• Add a screenshot to your theme: Not required, but makes your theme consistent with the others and keeps it from appearing as if something is missing.
• Create/edit the comments in your style.css: Same reason as #2
• Keep your theme slim by removing unnecessary files, but plan ahead. Be careful with what you’re removing if you may need it later.
• Don’t allow the 404 page to appear broken.
• Plan whether to use functions.php or a plugin – or both!
• Comments and documentation will not only tell that other developer what you were thinking, but will remind future you what you were thinking the last time you touched the theme. Trust me, it’s worth it.
• Write clean, modular, readable code that adheres to the WordPress standards.
• Keep the dashboard UI in mind, managing content should be manageable.

Also blabbed on about apples and dishes, but let’s forget about that. 🙂 I’m interested in how others approach creating their themes or if others have tips to offer as well. This post is mostly my opinion although I do provide as much reference as I can for what I’m basing that opinion on – but I have an open mind. Share your thoughts – looking forward to it!