Tiny rules for how to name things in CSS and JS

Raw

tinyRules.css.md

Tiny rules for how to name stuff

CSS

How to name CSS classes

Stateful Class names

Is it a state that is only one of two conditions? (i.e. a boolean)

Prefix with is/has

Is it a state that is determined by something on its own element?

use .is; that describes the element's own state

e.g. .isOverflowHidden .isHidden .isScrollable

Is it a state that is determined by its children?

use .has; this describes the state of something inside the element
try to make the end part a noun

e.g. .hasOverflowHidden .hasHiddenChildren .hasScrollableChildren

Is it a state that is a negative ?

if you can, avoid this because it can be hard to use; try to re-write as a positive
Use isNot and/or hasNo
Use an adjective for "is"
Try to stick a noun at the end for "has"; "Els" is a fine abbreviation for elements
if all else fails, add "able"

e.g.: .isNotHidden, .hasNoHiddenEls .isNotScrollable, .hasNoScrollable, .hasNoScrollableEls

In general, try to write the class in a way that it directly answers a close-ended question that could start with is, has, will, did, can, or should.

Is it a CSS class that JavaScript needs?

Prefix with js/ui

Does JavaScript need it just to find it (no CSS being set)?

use .js

e.g. .jsSubmitButton .jsVideoPlay

Does JavaScript need to change it so that CSS can style it?

use .ui
use an adjective or a past-tense

e.g. .uiSubmitted .uiVideoPlayed

Does a Test need it?

use .qa

Are these classnames for a component/module?

Avoid words that prescribe the content
Avoid words that prescribe the markup
Avoid ambiguously describing scope or presentation
Avoid using words to describe variation or relationships

e.g.: avoid these

.logos // suggests it can only have logos (prescribed content)
.logoList // suggests can only be used with ul, ol, dl (prescribed markup)
.logoGridList // suggests it always makes it looks like a grid (ambiguous presentation)
.darkLogoGridList //not obviously related, (words describe variation or relation)
.logoGridListBlack // Not clear what is black (ambiguous scope)

Prefer words that describe the purpose
Prefer describing scope
- Consider abbreviating scope if meaning can be obvious
Prefer convention to prescribe variations
Prefer convention to describe relationships

e.g. prefer these:

.mediaSet // 'Set' -> purpose, 'media' -> scope (could apply to video, picture, img)
.mediaSet--grid-md // '--' -> variation by convention, 'grid' -> purpose  , 'md' -> scope (abbreviated)
.mediaSet--theme-dark // '--' -> variation by convention, 'theme' -> scope, '-dark' -> variation
.mediaSet__media // '__' -> relationship by convention , 'media' ->  purpose

BEM is a well-known convention that helps address relationships and variations. You don't have to use BEM; you just have to be consistent.

Should I Use hyphens or underscores to separate a class prefix?

Be consistent
If everyone else is using hyphens, you should, too.
If you're the first person on the project, use camelCase; it's easier to select camelCased text in an IDE than it is hyphenated text

Is this a SRP (single responsibility principle) kind of class?

Sometimes a class only has one property because it's used in combination with other classes.

Don't use the value of a specific CSS property
Do give the purpose of that specific CSS property
Avoid suggesting usage with only specific HTML elements
Try suggesting usage with kinds of content

e.g. Avoid this:

 .button--yellow {
  color: yellow;
 }

And instead try this:

 .button--warn {
   color: yellow 
 }

Avoid this:

 .imgFloatLeft {
  float: left;
 }
 
 .imgFloatRight {
  float: right;
 }

And instead try

.rtfMedia--left {
 float: left;
}

.rtfMedia--right {
 float: right;
}

Sass/SCSS/Stylus/CSS naming

Variables for Colors

don't let the variable name indicate the variable value (what if the value changes)
indicate relative aspects of the value like hue, lightness

use relatives and superlatives (er, est) for variations on a hue

 --colorNeutralDarkest
 --colorNeutralDarker
 --colorNeutralDark
 --colorWarmDarker
 --colorWarmerDarkest

Generic Variables

Is the variable going to be used more than once?

start with the UI element name
end with the CSS property it affects

never put any information about the value of the variable in the name

  $linkColor: rgb(165,220,220,220)
  --linkColor: var(--colorCoolDark)

Is this variable used more than once, but there's a different variable for pseudo classes?

start with the UI element name
Then add the CSS property it affects

End with the state

  $linkColor: rgb(165,220,220);
  $linkColorHover: rgb(165,165,220);
  --linkColorHover: var(--colorCoolDarker);

Is the variable used once?

start with class name that the variable is used in

end with the CSS property it affects

  .foo {
      $fooHeight: $containerHeight / 3;
      width: $fooHeight / 2;
      height: $fooHeight;
  }

Raw

tinyRules.js.md

JS Naming

Functions that return things

Does the function return a boolean?

Prefix with "is" or "has"
Use "is" with an adjective
Use "has" with a noun
Avoid using a negative

e.g.

function isHot() {
 if (temperature > 100 ) {
   return false;
 } else {
   return true;
 }
}

function hasEggs(carton) { 
  if (carton.eggs.length > 0 ) { 
    return true;
  } else { 
    return false;
  }
}

Does the function return anything else ?

Prefix with get
End with thing it returns

Use a plural form if it returns an enumerable

  function getTemperature () {
    return temperature;
  }
  
  function getEggs() {
    const eggs = [];
    return eggs;
  }

Are you assigning the thing that the function returns to a variable?

Use the noun part of the function

const foods = getFoods();
const number = addNumbers();

Functions that do things

Start with a verb, end with a noun
Make the noun the thing that is the recipient of the action:

e.g.

calculateTemperature()
findThermometer();

Looping through stuff

Avoid using single-letter variable names (e.g. i);
Use at least-three letters.

Is the loop a`.forEach` on an array or array-like structure?

Make the array's noun its plural form

Make the item iterated on the singular form

 const fruits = ['banana', 'avocado', 'tomato'];

 fruits.forEach((fruit) => {

 });

Does the `.forEach` need an index?

Start with idx

Avoid single-letter variable names

 const fruits = ['banana', 'avocado', 'tomato'];

 fruits.forEach((fruit, idx) => {

 });

If you have to go more than one level deep, append idx to the item name:

    const foodGroups = [ ['banana', 'avocado', 'tomato'], ['steak', 'sausage' ] ];
    
    foodGroups.forEach((foodGroup, idx ) => {
    
        foodGroup.forEach((food, foodIdx) => {
        
        });
    });

Is the loop using `for in` or `for of` ?

Make the object/array's noun a plural form
Start any counter variables with idx
If you have to go more than one level deep, append idx to the item name

for (let idx = 0, fruit; idx < fruits.length; ++idx) { fruit = fruits[idx]; for (let goodFruitIdx = 0; goodFruit; goodFruitIdx < goodFruits.length; ++goodFruitIdx) { goodFruit = goodFruits[goodFruitIdx] } }

Functions in General

Complex Functions (functions with many parts)

Sometimes, the difficulty in naming a function comes from the fact that it does many things (has complexity).

Identitfy all of the tasks within this function (units of work that have single, testable activities)
Name those tasks (they either do or they return)
Create functions whose names represent their tasks
Re-evaluate the function now that it is a collection of named tasks and create a name that summarizes those tasks

Instead of this:

function getLiElement(titleNode) { // function name somewhat generic
    const listEl = document.createElement('li');
    
    const { tagName} = titleNode;
    let type = 'biggest';
	
    switch (tagName) { // task that determines a class name
	case 'H3':
		type = 'bigger';
		break;
	case 'H4':
		type = 'big';
		break;
	case 'H5':
		type = 'base';
		break;
	defaut:
		break;
		
    }
    const itemTypeClass = `articleTOC__item--${type}`;
    listEl.classList.add('articleTOC__item');
    listEl.classList.add(itemTypeClass);
    
    return listEl;
}

Prefer this

// function that does one thing with name that reflects what it does
function getTOCItemType(titleNode) {
	if (!titleNode) return;
		const { tagName} = titleNode;
		let type = 'biggest';
		
		switch (tagName) {
			case 'H3':
				type = 'bigger';
				break;
			case 'H4':
				type = 'big';
				break;
			case 'H5':
				type = 'base';
				break;
			defaut:
				break;
		}
		
		return `articleTOC__item--${type}`;
	}
 

function getTOCItemElement(titleNode) {
		const listEl = document.createElement('li');
		// variable that summarizes what the other function has done
        const tocElementTypeClassname = getTOCItemType(titleNode);
		
		listEl.classList.add('articleTOC__item');
		listEl.classList.add(tocElementTypeClassname);
		return listEl;																		
	}

Complicated functions (functions that are difficult to read)

Sometimes, the difficulty in naming a function comes from the fact that parts of it are confusing to read (it's complicated).

Determine if it is complex. If it is, make it less so.
Look at comparison operations (if, switch) and determine if it is self-evident what the logic is doing
- Consider creating a variable for each logical comparison (follow the guidance for how to name boolean variables)
- Consider creating a variable that summarizes the logical comparisons
Eliminate "magic numbers" and "magic strings" (values that exist, but their reason for being those values is not self-evident)
- Consider moving numbers in a setTimeout to variables
- Consider making values used for validing parameters their own variables