Naming Convention Best Practices

Consistency in naming conventions is crucial across projects to enhance readability and maintainability. Here’s a structured approach to naming files and directories in a way that aligns with common standards while keeping the design consistent.

General Principles

• Use Lowercase Letters: All filenames should be in lowercase to avoid case sensitivity issues.

• Avoid Spaces: Instead of spaces, use hyphens (-) or underscores (_) to separate words.

• Concise Yet Descriptive: Filenames should clearly describe the content without being overly long.

• Consistent Naming Conventions: Maintain the same naming style across all project files.

• Avoid Special Characters: Stick to letters, numbers, hyphens, and underscores to prevent unexpected errors.

PHP Files

• Singular Nouns for Class Files: For class definitions, use singular nouns (e.g., class-block.php).

• Plural Nouns for Collection/Utility Files: Use plural nouns for files that handle multiple instances or utilities (e.g., blocks-manager.php).

• Interface Prefix: Prefix interface files with interface- (e.g., interface-renderable.php).

• Trait Prefix: Prefix trait files with trait- (e.g., trait-singleton.php).

• Theme Functions: Use functions.php for theme-related functions.

JavaScript Files

• Kebab-case for General JS Files: Use kebab-case for general JavaScript files (e.g., block-editor.js).

• PascalCase for React Components: Use PascalCase for React component files (e.g., CustomButton.js).

• Test Files: Append .test.js or .spec.js for test files (e.g., CustomButton.test.js)

• Main Entry Points: Use index.js for main entry points or when exporting multiple components.

CSS/SCSS Files

• Kebab-case for Stylesheets: Use kebab-case for CSS filenames (e.g., main-styles.css).

• Prefix Partial SCSS Files: Prefix partial SCSS files with an underscore (e.g., _variables.scss).

• Descriptive Names for Component Styles: Use descriptive names for stylesheets specific to components (e.g., header-navigation.scss).

Block-specific Files

• Consistent Prefixes: Use consistent prefixes for block-related files (e.g., block-hero.php, block-hero.js, block-hero.scss).

• Grouped by Block Names: Organize block files into directories named after the block (e.g., /blocks/hero/).

Template Files

• Standard WordPress Naming: Use standard naming conventions (e.g., single.html, archive.html).

• Custom Template Prefix: Prefix custom template files with template-(e.g., template-landing-page.html).

Include Files

• Prefix Include Files: Use inc- or place them in an inc directory (e.g., inc-helpers.php or /inc/helpers.php).

Asset Files (Images, Fonts, etc.)

• Lowercase and Hyphens: Use lowercase and hyphens for asset filenames (e.g., hero-background.jpg, open-sans-bold.woff).

• Dimensions in Filenames: Include dimensions in filenames when relevant (e.g., logo-300x100.png).

Configuration Files

• Standard Names: Use standard names for common config files (e.g., .eslintrc.js, webpack.config.js).

• Custom Config Prefix: Prefix custom config files with config– (e.g., config-blocks.php).

Version Control and Deployment Files

• Standard Naming: Use standard names for version control and deployment files (e.g., .gitignore, .travis.yml, Dockerfile).

Documentation Files

• Uppercase for Top-level Documentation: Use uppercase for primary documentation files (e.g., README.md, CHANGELOG.md).

• Lowercase for Other Documentation: Use lowercase for additional documentation files (e.g., contributing.md).

Localization Files

• WordPress Conventions: Follow WordPress localization conventions (e.g., de_DE.po, fr_FR.mo).

Database Migration Files

• Timestamps or Version Numbers: Include timestamps or version numbers in migration filenames (e.g., 2023_07_16_create_users_table.php).

By adhering to these naming conventions, developers can create a coherent structure that improves collaboration, code readability, and maintainability across projects.