extern/naming-cheatsheet
1
0
Fork 1
mirror of https://github.com/kettanaito/naming-cheatsheet.git synced 2025-08-09 06:45:00 +02:00
Code Issues Packages Projects Releases Wiki Activity

Updates README

Browse Source
This commit is contained in:
Artem Zakharchenko
2018-09-13 10:28:54 +02:00
parent c9a1d0a4e3
commit cd8ae94a2b
1 changed files with 100 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
README.md
View File

@ -5,99 +5,91 @@
</p> </p>
# Naming cheatsheet # Naming cheatsheet
Naming things is hard. Let's make it easier. Naming things is hard. This sheet attempts to make it easier.
This document contains systematized concepts and patterns often used when naming variables. Although these suggestions can be applied to any programming language, I will use JavaScript to illustrate them in practice.
## Summary ## Naming convention
* [Guidelines](#guidelines) Pick **one** naming convention and follow it. It may be `likeThis`, or `like_this`, or anyhow else, it does not matter. What matters is for it to remain consistent.
* [HC/LC Pattern](#hclc-pattern)
* **[Actions](#actions)**
* [get](#get)
* [set](#set)
* [reset](#reset)
* [fetch](#fetch)
* [remove](#remove)
* [delete](#delete)
* [compose](#compose)
* [handle](#handle)
* **[Prefixes](#prefixes)**
* [is](#is)
* [has](#has)
* [should](#should)
* [min/max](#minmax)
* [prev/next](#prevnext)
## Guidelines
* Pick **one** naming convention and follow it. Whether it is `likeThis`, or `like_this`, or anyhow else, it does not matter. What matters is consistency in your code.
```js ```js
/* Bad */ /* Bad */
const pages_count = 5; const pages_count = 5
const shouldUpdate = true; const shouldUpdate = true
/* Good */ /* Good */
const pagesCount = 5; const pagesCount = 5
const shouldUpdate = true; const shouldUpdate = true
/* Good as well */ /* Good as well */
const pages_count = 5; const pages_count = 5
const should_update = true; const should_update = true
``` ```
* Name, whether of a variable, method, or something else, should be *short*, *descriptive* and *intuitive*: ## S-I-D
* **Short**. Variable should not take long to type and, therefore, to remember,
* **Descriptive**. Name of the variable should reflect what it does/possesses in the most efficient way, A name must be *short*, *intuitive* and *descriptive*:
* **Intuitive**. Name of the variable should read naturally, as close to the common speach as possible * **Short**. A name must not take long to type and, therefore, to remember,
* **Intuitive**. Name must read naturally, as close to the common speach as possible
* **Descriptive**. Name must reflect what it does/possesses in the most efficient way,
```js ```js
/* Bad */ /* Bad */
const a = 5; // "a" could mean anything const a = 5 // "a" could mean anything
const isPaginatable = (postsCount > 10); // "Paginatable" sounds extremely unnatural const isPaginatable = (postsCount > 10) // "Paginatable" sounds extremely unnatural
const shouldPaginatize = (postsCount > 10); // Made up verbs are so much fun! const shouldPaginatize = (postsCount > 10) // Made up verbs are so much fun!
/* Good */ /* Good */
const postsCount = 5; const postsCount = 5
const shouldDisplayPagination = (postsCount > 10); const shouldDisplayPagination = (postsCount > 10)
``` ```
* Do *not* use contractions. The latter contribute to nothing but decreased code readability. Finding a short, descriptive name may be hard, but don't think contractions help you in any way. ## Avoid contractions
Do **not** use contractions. They contribute to nothing but decreased readability of your code. Finding a short, descriptive name may be hard, but contraction is not an excude to not doing so.
```js ```js
/* Bad */ /* Bad */
const onItmClck = () => {}; const onItmClk = () => {}
/* Good */ /* Good */
const onItemClick = () => {}; const onItemClick = () => {}
``` ```
* Name should not duplicate the context when the latter is known, and when removing the context does not decrease the name's readability: ## 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 ```js
class MenuItem { class MenuItem {
/* Method name duplicates the context it is in (which is "MenuItem") */ /* Method name duplicates the context (which is "MenuItem") */
handleMenuItemClick = (event) => { ... } handleMenuItemClick = (event) => { ... }
/* This way it reads as MenuItem.handleClick() */ /* Reads nicely as `MenuItem.handleClick()` */
handleClick = (event) => { ... } handleClick = (event) => { ... }
} }
``` ```
* Name should reflect the expected result:
```js ## Reflect expected result
A name should reflect the expected result.
```jsx
/* Bad */ /* Bad */
const isEnabled = (itemsCount > 3); const isEnabled = (itemsCount > 3)
return (<Button disabled={!isEnabled} />); return <Button disabled={!isEnabled} />
/* Good */ /* Good */
const isDisabled = (itemsCount <= 3); const isDisabled = (itemsCount <= 3)
return (<Button disabled={isDisabled} />); return <Button disabled={isDisabled} />)
``` ```
--- ---
## HC/LC Pattern # Naming functions
There is a useful pattern you may follow when naming your methods:
## A/HC/LC Pattern
There is a useful pattern to follow when naming functions:
``` ```
prefix? + action (A) + high context (HC) + low context? (LC) prefix? + action (A) + high context (HC) + low context? (LC)
@ -112,13 +104,14 @@ To illustrate, take a look at how this pattern may be applied in the table below
| `handleClickOutside` | | `handle` | `Click` | `Outside` | | `handleClickOutside` | | `handle` | `Click` | `Outside` |
| `shouldDisplayMessage` | `should` | `Display` | `Message`| | | `shouldDisplayMessage` | `should` | `Display` | `Message`| |
> **Note:** The order of the contexts affects the core meaning of a method. For example, `shouldUpdateComponent` means *you* are about to update a component, while `shouldComponentUpdate` tells you that *component* will update on itself, and you are but controlling whether it should do that right now. > **Note:** Context order affects the meaning of a method. For example, `shouldUpdateComponent` means *you* are about to update a component, while `shouldComponentUpdate` tells you that *component* will update on itself, and you are but controlling whether it should do that right now.
In other words, **high context emphasizes the meaning of the variable**. In other words, **high context emphasizes the meaning of a variable**.
--- ---
## Actions ## Actions
Chosing a proper action name may grant explicit descriptiveness to your methods. This is a good place to start when naming your methods.
The verb part of your function name. The most important part responsible for describing what the function *does*.
#### `get` #### `get`
Accesses data immediately (i.e. shorthand getter of internal data). Accesses data immediately (i.e. shorthand getter of internal data).
@ -132,13 +125,13 @@ function getFruitsCount() {
Declaratively sets a variable with value `A` to value `B`. Declaratively sets a variable with value `A` to value `B`.
```js ```js
const fruits = 0; const fruits = 0
function setFruits(nextFruits) { function setFruits(nextFruits) {
fruits = nextFruits; fruits = nextFruits
} }
setFruits(5); setFruits(5)
console.log(fruits) // 5 console.log(fruits) // 5
``` ```
@ -146,24 +139,24 @@ console.log(fruits) // 5
Sets a variable back to its initial value or state. Sets a variable back to its initial value or state.
```js ```js
const initialFruits = 5; const initialFruits = 5
const fruits = initialFruits; const fruits = initialFruits
setFruits(10); setFruits(10)
console.log(fruits); // 10 console.log(fruits) // 10
function resetFruits() { function resetFruits() {
fruits = initialFruits; fruits = initialFruits
} }
resetFruits(); resetFruits()
console.log(fruits); // 5 console.log(fruits) // 5
``` ```
#### `fetch` #### `fetch`
Requests for a data, which takes time (i.e. async request). Requests for a data, which takes time (i.e. async request).
```js ```js
function fetchPosts(postCount) { function fetchPosts(postCount) {
return fetch('https://api.dev/posts', { ... }); return fetch('https://api.dev/posts', { ... })
} }
``` ```
@ -173,16 +166,16 @@ 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): 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 ```js
const selectedFilters = ['price', 'availability', 'size']; const selectedFilters = ['price', 'availability', 'size']
function removeFilter(filterName) { function removeFilter(filterName) {
const filterIndex = selectedFilters.indexOf(filterName); const filterIndex = selectedFilters.indexOf(filterName)
if (filterIndex !== -1) { if (filterIndex !== -1) {
selectedFilters.splice(filterIndex, 1); selectedFilters.splice(filterIndex, 1)
} }
return selectedFilters; return selectedFilters
} }
``` ```
@ -193,7 +186,7 @@ Imagine you are a content editor, and there is that notorious post you wish to g
```js ```js
function deletePost(id) { function deletePost(id) {
return database.find({ id }).delete(); return database.find({ id }).delete()
} }
``` ```
@ -202,7 +195,7 @@ Creates a new data from the existing one. Mostly applicable to strings or object
```js ```js
function composePageUrl(pageName, pageId) { function composePageUrl(pageName, pageId) {
return `${pageName.toLowerCase()}-${pageId}`; return `${pageName.toLowerCase()}-${pageId}`
} }
``` ```
@ -211,74 +204,79 @@ Handles a dedicated action. Often used in naming the callback methods.
```js ```js
function handleLinkClick(event) { function handleLinkClick(event) {
event.preventDefault(); event.preventDefault()
console.log('Clicked a link!'); console.log('Clicked a link!')
} }
link.addEventListener('click', handleLinkClick); link.addEventListener('click', handleLinkClick)
``` ```
--- ---
## Prefixes ## Context
Prefixes act as enhancers, indicating additional meaning behind variables.
#### `is` A domain that a function operates on.
Describes certain characteristic or state of the current context (returns `Boolean`).
---
## Prefixes
Prefix enhances the meaning of a variable.
### `is`
Describes certain characteristic or state of the current context (returns `boolean`).
```js ```js
const color = 'blue'; const color = 'blue'
const isBlue = (color === 'blue'); // characteristic const isBlue = (color === 'blue') // characteristic
const isPresent = true; // state const isPresent = true // state
if (isBlue && isPresent) { if (isBlue && isPresent) {
console.log('The color is blue and it is present!'); console.log('Blue is present!')
} }
``` ```
#### `has` ### `has`
Describes whether the current context possesses a certain value or state (returns `Boolean`). Describes whether the current context possesses a certain value or state (returns `boolean`).
```js ```js
/* Bad */ /* Bad */
const isProductsExist = (productsCount > 0); const isProductsExist = (productsCount > 0)
const areProductsPresent = (productsCount > 0); const areProductsPresent = (productsCount > 0)
/* Good */ /* Good */
const hasProducts = (productsCount > 0); const hasProducts = (productsCount > 0)
``` ```
#### `should` ### `should`
Reflects a positive conditional statement (returns `Boolean`) tightly coupled with a certain action. Reflects a positive conditional statement (returns `Boolean`) tightly coupled with a certain action.
```js ```js
const currentUrl = 'https://dev.com'; function shouldUpdateUrl(url, expectedUrl) {
return (url !== expectedUrl)
function shouldUpdateUrl(url) {
return (url !== currentUrl);
} }
``` ```
#### `min`/`max` ### `min`/`max`
Represent minimum or maximum value. Useful for describing boundaries or allowed limits. Represent minimum or maximum value. Useful for describing boundaries or limits.
```js ```js
function PostsList() { function PostsList() {
this.minPosts = 3; this.minPosts = 3
this.maxPosts = 10; this.maxPosts = 10
} }
``` ```
#### `prev`/`next` ### `prev`/`next`
Indicate the previous and the next state of a variable in the current context. Useful for describing state transitions. Indicate the previous and the next state of a variable in the current context. Useful for describing state transitions.
```jsx ```jsx
function fetchPosts() { function fetchPosts() {
const prevPosts = this.state.posts; const prevPosts = this.state.posts
const fetchedPosts = fetch('...'); const fetchedPosts = fetch('...')
const nextPosts = prevPosts.merge(fetchedPosts); const nextPosts = prevPosts.merge(fetchedPosts)
return this.setState({ posts: nextPosts }); return this.setState({ posts: nextPosts })
} }
``` ```