Naming Conventions

When naming things (components, files, functions, classes, data attributes, arguments, etc…), the following conventions provide consistent, easy-to-understand, maintainable names:

Be Clear, Concise, and Descriptive

A great name should clearly describe the purpose of the thing it's naming using as few words as possible to do so. For instance, when naming an argument for an image's alternative text, instead of calling it textDescribingImageForScreenReadersOrIfImageDoesNotLoad, naming it simply alt, per our usage of common abbreviations, or image.alt, per our use of context principle, is preferred. A simpler example may be using published instead of datePublished provided that published is understood to only allow for a date input.

If a name requires more than one word, all words that make up the name should read together either as a proper noun or as a grammatically correct sentence starting with the verb. For example, a function that discovers and initializes plugins could be called discoverPlugins or PluginDiscoverer but should not be called pluginsDiscover.

Some things being named have an implicit verb associated with them, for instance component macros imply the verb display. Names of things with implicit verbs should read as if that verb is included in the name, so a component named feature-content is better named featured-content as it forms a more correct sentence; similarly, a component named attribute is better named attribution.

Avoid Generalities

A corollary of Be Concise and Descriptive is to avoid generalities when naming things. For instance, data used as a generic grouping doesn't provide a descriptive enough name of what an item is to be helpful to discern its intent. content, on the other hand, can go either way; used as a straight replacement for data may still be too generic, but when used to describe a specific portion of an item may be descriptive enough.

Additionally, when naming an item, avoid terms that could be applied generally unless coupled with a specific identifier that includes enough context to uniquely distinguish its use. For instance, a component named short-content is likely too generic to be useful, but featured-content (or better, hero--featured, see examples next) provides context that this component should only be used where some content needs to be distinguished from the content around it, and that that content is featured in some way.

Examples of common generic words used throughout the codebase, and where one may use them, follow. Much like HTML semantics, when using these generalities, if more than one are appropriate, use the most specific descriptor possible.

Word	Description
card	Self-contained preview of content at a separate URL, usually with multiple of the same displayed together
hero	Eye-catching call out of content, usually at a separate URL, displayed alone from other heros of the same display
item	Array of data that all shares the same shape (all strings, all the type of object, etc…)

If a generality must be used and alternative versions are needed, name the alternatives starting with the generality, so card--icon instead of icon-card in order to enable fast scanning and grouping of related items.

Use Ordinal Numbering

In order to remain consistent, when items are not contained within an array and have a specific order or hierarchy, use linguistic ordinal numerals to describe them, for instance primary and secondary instead of main and auxiliary.

Assuming First or Last

A corollary of using ordinal numbering is, depending on the context, assume that if there are multiple options for items ordered spatially or chronologically and only one items is requested, that either the first or the last item is meant to be used (and therefore doesn't need to be included in the the name). For instance, when talking about the updated date of an article and only one date is displayed, instead of calling that variable lastUpdated, it should be shortened to updated.

Use Context

All items are understood within some context. Items in an object, for instance, inherit the context of their parent, but items that are part of a shared namespace, for instance components, need to take into account all of their siblings when naming. Because of this, it's best to include context when context otherwise may not be clear, either by nesting items in a contextual parent, or by ensuring that context isn't required to understand an item's name. A good rule of thumb, especially for naming arguments: if the name you're writing includes descriptors, such as companyName and companyOrg, you likely want to divide that out into higher-order groups with sub-items, which here would be company and name and org respectively.

Avoid Default

A corollary of Use Context is to avoid default when naming things. A default always requires context, and that context will almost always not be available. When context is available, following the Be Concise and Descriptive rule, it's better to omit default in favor of only naming alternatives.

Use Common Abbreviations

When naming, common abbreviations can be used in order to facilitate shortening otherwise long words or phrases. Examples of common abbreviations used throughout the codebase are as follows:

Abbreviation	Abbreviated
alt	Alternative, Alternative Text
app	Application
args	Arguments
bkg	Background
cta	Call to Action
desc	Description
dest	Destination
docs	Documentation
dir	Direction, Directory
elem	Element
img	Image
init	Initialization
lang	Language
max	Maximum
min	Minimum
nav	Navigation
src	Source
ssi	Service Side Include
stat	Statistic
toc	Table of Contents

Examples

The following are examples of a bad name, a good alternative, and a description as to why the good alternative is preferred.

• Alternative text for profile data. The first example is bad because it restates the expected content without providing clarity as to what the content may be used for. The second example is better because it makes clear what this content is used for, with bonus points for using a common abbreviation.
  • ❌ Bad:

  profile:
    profilePictureOf: Profile picture of ((t))

  • ✅ Good:

  profile:
    alt: Profile picture of ((t))

• Related YAML attributes for author data. The first example is bad because the association, and therefore context, between author, name, and the parts of a name, is lost when collapsed into a single attribute name. The second example is good because it preserves that association/context.
  • ❌ Bad:

  authorGivenName: Llama
  authorLastName: Jones

  • ✅ Good:

  author:
    name:
      given: Llama
      last: Jones

• Component displaying the majority of content on landing pages. The first example is bad because the use of default doesn't adequately describe the context under which this component should be used. The second option is better because it provides context for where this should be used.
  • ❌ Bad: default-content
  • ✅ Good: card-landing
• Hero component. The first example is bad because default should be avoided when naming the base version of a component, with only alternatives named. The second example is good because it simply names the component.
  • ❌ Bad: heroDefault
  • ✅ Good: hero