Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kettanaito/naming-cheatsheet
Comprehensive language-agnostic guidelines on variables naming. Home of the A/HC/LC pattern.
https://github.com/kettanaito/naming-cheatsheet
action cheatsheet guideline guidelines high-context low-context naming naming-cheatsheet naming-conventions naming-pattern naming-schemes pattern prefix variables
Last synced: about 1 month ago
JSON representation
Comprehensive language-agnostic guidelines on variables naming. Home of the A/HC/LC pattern.
- Host: GitHub
- URL: https://github.com/kettanaito/naming-cheatsheet
- Owner: kettanaito
- License: mit
- Created: 2017-06-30T07:46:04.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2024-03-13T22:39:17.000Z (6 months ago)
- Last Synced: 2024-05-22T16:24:11.812Z (4 months ago)
- Topics: action, cheatsheet, guideline, guidelines, high-context, low-context, naming, naming-cheatsheet, naming-conventions, naming-pattern, naming-schemes, pattern, prefix, variables
- Homepage:
- Size: 54.7 KB
- Stars: 13,677
- Watchers: 118
- Forks: 858
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
- awesome - kettanaito/naming-cheatsheet - Comprehensive language-agnostic guidelines on variables naming. Home of the A/HC/LC pattern. (miscellaneous)
- awesome-github-repos - kettanaito/naming-cheatsheet - Comprehensive language-agnostic guidelines on variables naming. Home of the A/HC/LC pattern. (Others)
- jimsghstars - kettanaito/naming-cheatsheet - Comprehensive language-agnostic guidelines on variables naming. Home of the A/HC/LC pattern. (Others)
README
# Naming cheatsheet
- [English language](#english-language)
- [Naming convention](#naming-convention)
- [S-I-D](#s-i-d)
- [Avoid contractions](#avoid-contractions)
- [Avoid context duplication](#avoid-context-duplication)
- [Reflect the expected result](#reflect-the-expected-result)
- [Naming functions](#naming-functions)
- [A/HC/LC pattern](#ahclc-pattern)
- [Actions](#actions)
- [Context](#context)
- [Prefixes](#prefixes)
- [Singular and Plurals](#singular-and-plurals)
---
Naming things is hard. This sheet attempts to make it easier.
Although these suggestions can be applied to any programming language, I will use JavaScript to illustrate them in practice.
## English language
Use English language when naming your variables and functions.
```js
/* Bad */
const primerNombre = 'Gustavo'
const amigos = ['Kate', 'John']
/* Good */
const firstName = 'Gustavo'
const friends = ['Kate', 'John']
```
> Like it or not, English is the dominant language in programming: the syntax of all programming languages is written in English, as well as countless documentations and educational materials. By writing your code in English you dramatically increase its cohesiveness.
## Naming convention
Pick **one** naming convention and follow it. It may be `camelCase`, `PascalCase`, `snake_case`, or anything else, as long as it remains consistent. Many programming languages have their own traditions regarding naming conventions; check the documentation for your language or study some popular repositories on GitHub!
```js
/* Bad */
const page_count = 5
const shouldUpdate = true
/* Good */
const pageCount = 5
const shouldUpdate = true
/* Good as well */
const page_count = 5
const should_update = true
```
## S-I-D
A name must be _short_, _intuitive_ and _descriptive_:
- **Short**. A name must not take long to type and, therefore, remember;
- **Intuitive**. A name must read naturally, as close to the common speech as possible;
- **Descriptive**. A name must reflect what it does/possesses in the most efficient way.
```js
/* Bad */
const a = 5 // "a" could mean anything
const isPaginatable = a > 10 // "Paginatable" sounds extremely unnatural
const shouldPaginatize = a > 10 // Made up verbs are so much fun!
/* Good */
const postCount = 5
const hasPagination = postCount > 10
const shouldPaginate = postCount > 10 // alternatively
```
## Avoid contractions
Do **not** use contractions. They contribute to nothing but decreased readability of the code. Finding a short, descriptive name may be hard, but contraction is not an excuse for not doing so.
```js
/* Bad */
const onItmClk = () => {}
/* Good */
const onItemClick = () => {}
```
## Avoid context duplication
A name should not duplicate the context in which it is defined. Always remove the context from a name if that doesn't decrease its readability.
```js
class MenuItem {
/* Method name duplicates the context (which is "MenuItem") */
handleMenuItemClick = (event) => { ... }
/* Reads nicely as `MenuItem.handleClick()` */
handleClick = (event) => { ... }
}
```
## Reflect the expected result
A name should reflect the expected result.
```jsx
/* Bad */
const isEnabled = itemCount > 3
return
/* Good */
const isDisabled = itemCount <= 3
return
```
---
# Naming functions
## A/HC/LC Pattern
There is a useful pattern to follow when naming functions:
```
prefix? + action (A) + high context (HC) + low context? (LC)
```
Take a look at how this pattern may be applied in the table below.
| Name | Prefix | Action (A) | High context (HC) | Low context (LC) |
| ---------------------- | -------- | ---------- | ----------------- | ---------------- |
| `getUser` | | `get` | `User` | |
| `getUserMessages` | | `get` | `User` | `Messages` |
| `handleClickOutside` | | `handle` | `Click` | `Outside` |
| `shouldDisplayMessage` | `should` | `Display` | `Message` | |
> **Note:** The order of context affects the meaning of a variable. For example, `shouldUpdateComponent` means _you_ are about to update a component, while `shouldComponentUpdate` tells you that _component_ will update itself, and you are only controlling _when_ it should update.
> In other words, **high context emphasizes the meaning of a variable**.
---
## Actions
The verb part of your function name. The most important part responsible for describing what the function _does_.
### `get`
Accesses data immediately (i.e. shorthand getter of internal data).
```js
function getFruitCount() {
return this.fruits.length
}
```
> See also [compose](#compose).
You can use `get` when performing asynchronous operations as well:
```js
async function getUser(id) {
const user = await fetch(`/api/user/${id}`)
return user
}
```
### `set`
Sets a variable in a declarative way, with value `A` to value `B`.
```js
let fruits = 0
function setFruits(nextFruits) {
fruits = nextFruits
}
setFruits(5)
console.log(fruits) // 5
```
### `reset`
Sets a variable back to its initial value or state.
```js
const initialFruits = 5
let fruits = initialFruits
setFruits(10)
console.log(fruits) // 10
function resetFruits() {
fruits = initialFruits
}
resetFruits()
console.log(fruits) // 5
```
### `remove`
Removes something _from_ somewhere.
For example, if you have a collection of selected filters on a search page, removing one of them from the collection is `removeFilter`, **not** `deleteFilter` (and this is how you would naturally say it in English as well):
```js
function removeFilter(filterName, filters) {
return filters.filter((name) => name !== filterName)
}
const selectedFilters = ['price', 'availability', 'size']
removeFilter('price', selectedFilters)
```
> See also [delete](#delete).
### `delete`
Completely erases something from the realms of existence.
Imagine you are a content editor, and there is that notorious post you wish to get rid of. Once you clicked a shiny "Delete post" button, the CMS performed a `deletePost` action, **not** `removePost`.
```js
function deletePost(id) {
return database.find({ id }).delete()
}
```
> See also [remove](#remove).
> **`remove` or `delete`?**
>
> When the difference between `remove` and `delete` is not so obvious to you, I'd suggest looking at their opposite actions - `add` and `create`.
> The key difference between `add` and `create` is that `add` needs a destination while `create` **requires no destination**. You `add` an item _to somewhere_, but you don't "`create` it _to somewhere_".
> Simply pair `remove` with `add` and `delete` with `create`.
>
> Explained in detail [here](https://github.com/kettanaito/naming-cheatsheet/issues/74#issue-1174942962).
### `compose`
Creates new data from the existing one. Mostly applicable to strings, objects, or functions.
```js
function composePageUrl(pageName, pageId) {
return pageName.toLowerCase() + '-' + pageId
}
```
> See also [get](#get).
### `handle`
Handles an action. Often used when naming a callback method.
```js
function handleLinkClick() {
console.log('Clicked a link!')
}
link.addEventListener('click', handleLinkClick)
```
---
## Context
A domain that a function operates on.
A function is often an action on _something_. It is important to state what its operable domain is, or at least an expected data type.
```js
/* A pure function operating with primitives */
function filter(list, predicate) {
return list.filter(predicate)
}
/* Function operating exactly on posts */
function getRecentPosts(posts) {
return filter(posts, (post) => post.date === Date.now())
}
```
> Some language-specific assumptions may allow omitting the context. For example, in JavaScript, it's common that `filter` operates on Array. Adding explicit `filterArray` would be unnecessary.
---
## Prefixes
Prefix enhances the meaning of a variable. It is rarely used in function names.
### `is`
Describes a characteristic or state of the current context (usually `boolean`).
```js
const color = 'blue'
const isBlue = color === 'blue' // characteristic
const isPresent = true // state
if (isBlue && isPresent) {
console.log('Blue is present!')
}
```
### `has`
Describes whether the current context possesses a certain value or state (usually `boolean`).
```js
/* Bad */
const isProductsExist = productsCount > 0
const areProductsPresent = productsCount > 0
/* Good */
const hasProducts = productsCount > 0
```
### `should`
Reflects a positive conditional statement (usually `boolean`) coupled with a certain action.
```js
function shouldUpdateUrl(url, expectedUrl) {
return url !== expectedUrl
}
```
### `min`/`max`
Represents a minimum or maximum value. Used when describing boundaries or limits.
```js
/**
* Renders a random amount of posts within
* the given min/max boundaries.
*/
function renderPosts(posts, minPosts, maxPosts) {
return posts.slice(0, randomBetween(minPosts, maxPosts))
}
```
### `prev`/`next`
Indicate the previous or the next state of a variable in the current context. Used when describing state transitions.
```jsx
async function getPosts() {
const prevPosts = this.state.posts
const latestPosts = await fetch('...')
const nextPosts = concat(prevPosts, latestPosts)
this.setState({ posts: nextPosts })
}
```
## Singular and Plurals
Like a prefix, variable names can be made singular or plural depending on whether they hold a single value or multiple values.
```js
/* Bad */
const friends = 'Bob'
const friend = ['Bob', 'Tony', 'Tanya']
/* Good */
const friend = 'Bob'
const friends = ['Bob', 'Tony', 'Tanya']
```