Naming Files & Directories

Some software expects or relies on certain directory structures and filenames (like /src in Gatsby, webpack.config.js in the root for wp-scripts, etc), while others aren’t prescriptive or reliant on specific naming and location.

As a result, naming is pretty conditional, but we have some general preferences and more specific practices.

General

Avoid abbreviations like /inc, /src and /bin

We generally prefer /includes, /source and /scripts. The notable exception is common technology acronyms like /css or /js instead of /cascading-style-sheets

/stylesheets or /javascript.

While Composer PSR-4 autoloading is case-insensitive, directory structures should reflect namespace capitalization

While /includes/admin/Menu.php works fine for \Newfold\WP\Module\Admin\Menu() with proper root-mapping to /includes, /includes/Admin/Menu.php is preferred.

WordPress

While we generally follow “the WordPres way,” for PSR-4 autoloaded files, we don’t use the class-{name}.php prefix common in WordPress Core.

Brand Plugins

We have the plugins setup with .distignore and .distinclude files which expect certain file organizations. We want our distribution files to be as small as possible but also contain any required files. Following a standard folder structure across our modules will ensure that we have files in proper places for this. To understand these rules please refer to these files in the plugin. They are followed for all build steps locally and via github workflows. For example, any tokens must be ignored in the distributed files and build files for security reasons, thus in the .distignore file we ignore all hidden dot files with the line ./*.

Modules

All newfold modules should be setup in a similar directory structure. This makes the files easy to find and simple to target certain files across all modules for the smallest zip file as possible. For example, we don’t need to include source javascript files, test files, or even config files in plugins, since those files arent used in this context and only end up taking up space. When a plugin is on hundreds of thousands of sites, this filesize discrepancy adds up quickly and leads more bandwidth and hosting space. Please follow these guidelines and ensure that any module’s required files are included in the final distributed plugin zip.

/includes

PHP files in the module beyond the bootstrap file and optionally another base file, should be located in an /includes directory. These files should be loaded with autoloading and properly namespaced.

/src or /source

Source javascript files should be located in a /src or preferably /source directory. According to the plugin level .distignore file, these source javascript files will not be included in the distributed plugin zip. If the module requires a build step the compiled javascript in the build directory will be included, but a build javascript step will likely lead to an npmjs or npm.pkg.github package.

/static

Any static files (such as images or css) should be placed in a /static directory (also acceptable is /assets) to ensure they are included in distribution zips.