Theme file structure best practice

You first need to ask yourself: Will this theme ever be maintained or used by other people than me? If so, read on, if not, you should only build code that will eventually make sense to you when getting back to this project after a few years.

If you are creating a theme that will be used by others, you should keep in mind that themes are supposed to be reusable in multiple use-cases. The WP way of doing that is through the use of child themes. All files in a theme will be loaded from the child theme, if they exist there, except for functions.php and style.css. So you should organize your file structure in a way that will allow people who use your theme to easily realize what files they need to copy and modify in the child theme in order to use your theme in ways you haven’t thought possible.

You should also group functionality that people should not temper with in a few heavy files, prone to updating and advise your users not to override those and put the rest of the stuff in functionality oriented files that could easily be overriden in a child theme.

A typical scheme for a theme would be:

/assets
    /js
    /css
    /img
/includes => put your core functionality here, especially if you go OOP
/lang     => your i18n files go here
/modules  => if you create any

That’s what I would use as a starter. When I write modules i think of advanced functionality that will only be used in some particular cases and is completely turned off in other cases. If you like things cleaner, you could move /modules in /includes.

If you are familiar with MCV frameworks, it is also a viable model for structuring a theme, even though it’s not as easy to understand for the average user.