Originally published on drupalconnect.com.
While human-readable titles should be consistent in engineered systems, the focus of this article targets code-related naming conventions. This guide is less about defining exactly what to do, but enable good decisions for any type of project.
Be consistent
This cannot be stressed enough. Predictability makes things much easier in programming... particularly when debugging or working with another person's code. Each project has it's own needs and industry language.
Create a small document that sets some general rules and various examples before starting to code. This is typically handled in an Information Architecture (IA) spreadsheet, which can be updated during the build (just notify the build team when changes are made). Identify terminology and description patterns. Have all developers on the project contribute to that document and adhere to it throughout the build process. Add this document to technical documentation that is provided to the client and archived for future reference by other developers.
Case sensitivity
Code is often case-sensitive, which can be utilized as a means of work separation or to aid readability. See camelCase and StudlyCaps. Always use lowercase characters for HTML tags and attributes.
Separation anxiety
Separation characters like dashes (-) and underscores (_) are used for readability and grouping related items, such as snake_case. However, be mindful of language-specific considerations. A dash in PHP should not be used in variable names (avoid $foo-bar), since it is an operator character. A dash can be used in a string in PHP for array keys (e.g. $example['foo-bar']), but it is not recommended.
Abbreviated
Abbreviations are another major consideration due to limitations on character length and to help reduce typing in code. If in doubt, look up an abbreviation for a word. The same abbreviations should be used throughout code, which should be documented properly before and as code is written.
Singular vs. Plural
This is somewhat debatable, but a few simple ideas can help make strong decisions. Database tables, queries/procedures, and fields can often use a bit of both. In general, think of an object container as singular, such as a contact. This can be difficult with things that end with an "s", so simply add the word "item" to the end (e.g. NewsItem instead of News). In the case of queries or procedures that produce zero to many item results, use a plural name (e.g. Contacts, BlogEntries). A similar approach can be considered with fields, where single-values are singular (e.g. product_id) and multi-values are plural (e.g. product_ids).
Drupal specific
Drupal and many contributed modules allow for configuration through the administrative interface. Several components are created with machine names, which are often unique identifiers. This includes things like names for content types, taxonomy vocabularies, fields, views (view name anddisplay name), blocks, rules, etc. CSS class names are derived from these names, come from patterns in modules, and can be defined. Most of these names are limited in character length, so be sure to establish abbreviation grouping and patterns in a team document.
Use singular names for content types and plural names for things that produce multiple results, like Views. So while course and news_item are content types, courses and news would be good names for Views that list those items.
Fields that are shared across Drupal entities should not be prefixed, but those that are specific to an entity should be prefixed if others could exist. For example, if we have a content type namedvehicle it might have a field_veh_id instead of field_id. Another content type part could then also use field_part_id, assuming there are key differences in how they are configured and used. Use singular names for single-value fields (e.g. field_event_loc) and use plural names for multi-value fields (e.g. field_event_dates)
All machine names should be defined properly before creating other components that reference them (e.g. don't make a context rule that references a view display if that display is namedblock_1). Changing a machine name too late will break things.
External references
Review documentation resources for programming languages and frameworks to understand general best practices. A few examples:
- JavaScript Coding Conventions
- Title CSS: A Simple Approach to CSS Class Naming
- CSS Naming Conventions: Less Rules, more Fun
- SASS CSS naming conventions
- PHP-FIG PSR-1 standard (specifically sections 3 and 4)
- Drupal coding standards
- Symfony coding standards
- Wordpress coding standards