holm/naming-cheatsheet
1
0
Fork 0
forked from extern/naming-cheatsheet
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Provides grammar fixes

Browse Source
This commit is contained in:
Artem Zakharchenko
2021-01-16 15:58:59 +01:00
parent dbd554dd60
commit 39fa584829
1 changed files with 44 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
README.md
View File

@ -5,12 +5,14 @@
</p> </p>
# Naming cheatsheet # Naming cheatsheet
Naming things is hard. This sheet attempts to make it easier. 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. Although these suggestions can be applied to any programming language, I will use JavaScript to illustrate them in practice.
## Naming convention ## Naming convention
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.
Pick **one** naming convention and follow it. It may be `cammelCase`, or `snake_case`, or anyhow else, it does not matter. What matters is for it to remain consistent.
```js ```js
/* Bad */ /* Bad */
@ -28,21 +30,22 @@ const should_update = true
## S-I-D ## S-I-D
A name must be *short*, *intuitive* and *descriptive*: A name must be _short_, _intuitive_ and _descriptive_:
* **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; - **Short**. A name must not take long to type and, therefore, remember;
* **Descriptive**. Name must reflect what it does/possesses in the most efficient way. - **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 ```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 hasPagination = (postsCount > 10) const hasPagination = postsCount > 10
const shouldDisplayPagination = (postsCount > 10) // alternatively const shouldDisplayPagination = postsCount > 10 // alternatively
``` ```
## Avoid contractions ## Avoid contractions
@ -65,7 +68,7 @@ A name should not duplicate the context in which it is defined. Always remove th
class MenuItem { class MenuItem {
/* Method name duplicates the context (which is "MenuItem") */ /* Method name duplicates the context (which is "MenuItem") */
handleMenuItemClick = (event) => { ... } handleMenuItemClick = (event) => { ... }
/* Reads nicely as `MenuItem.handleClick()` */ /* Reads nicely as `MenuItem.handleClick()` */
handleClick = (event) => { ... } handleClick = (event) => { ... }
} }
@ -77,11 +80,11 @@ A name should reflect the expected result.
```jsx ```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} />
``` ```
@ -99,28 +102,29 @@ prefix? + action (A) + high context (HC) + low context? (LC)
Take a look at how this pattern may be applied in the table below. Take a look at how this pattern may be applied in the table below.
| Name | Prefix | Action (A) | High context (HC) | Low context (LC) | | Name | Prefix | Action (A) | High context (HC) | Low context (LC) |
| ---- | ---- | ------ | ------------ | ----------- | | ---------------------- | -------- | ---------- | ----------------- | ---------------- |
| `getPost` | | `get` | `Post` | | | `getPost` | | `get` | `Post` | |
| `getPostData` | | `get` | `Post` | `Data` | | `getPostData` | | `get` | `Post` | `Data` |
| `handleClickOutside` | | `handle` | `Click` | `Outside` | | `handleClickOutside` | | `handle` | `Click` | `Outside` |
| `shouldDisplayMessage` | `should` | `Display` | `Message`| | | `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 on itself, and you are but controlling whether it should do that right now. > **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 on itself, and you are but controlling whether it should do that right now.
In other words, **high context emphasizes the meaning of a variable**. > In other words, **high context emphasizes the meaning of a variable**.
--- ---
## Actions ## Actions
The verb part of your function name. The most important part responsible for describing what the function *does*. 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).
```js ```js
function getFruitsCount() { function getFruitsCount() {
return this.fruits.length; return this.fruits.length
} }
``` ```
@ -162,6 +166,7 @@ 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', {...})
@ -170,13 +175,13 @@ function fetchPosts(postCount) {
### `remove` ### `remove`
Removes something *from* somewhere. 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
function removeFilter(filterName, filters) { function removeFilter(filterName, filters) {
return filters.filter(name => name !== filterName) return filters.filter((name) => name !== filterName)
} }
const selectedFilters = ['price', 'availability', 'size'] const selectedFilters = ['price', 'availability', 'size']
@ -193,7 +198,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()
} }
``` ```
@ -201,7 +206,7 @@ function deletePost(id) {
### `compose` ### `compose`
Creates a new data from the existing one. Mostly applicable to strings, objects, or functions. Creates new data from the existing one. Mostly applicable to strings, objects, or functions.
```js ```js
function composePageUrl(pageName, pageId) { function composePageUrl(pageName, pageId) {
@ -229,7 +234,7 @@ link.addEventListener('click', handleLinkClick)
A domain that a function operates on. A domain that a function operates on.
A function is often an action on *something*. It is important to state what is its operable domain, or at least an expected data type. A function is often an action on _something_. It is important to state what is its operable domain, or at least an expected data type.
```js ```js
/* A pure function operating with primitives */ /* A pure function operating with primitives */
@ -243,7 +248,7 @@ function getRecentPosts(posts) {
} }
``` ```
> Some language-specific assumptions may allow to omit the context. For example, in JavaScript it is common that `filter` operates on Array. Adding explicit `filterArray` would be unnecessary. > 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.
--- ---
@ -257,7 +262,7 @@ Describes a characteristic or state of the current context (usually `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) {
@ -271,11 +276,11 @@ Describes whether the current context possesses a certain value or state (usuall
```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`
@ -284,11 +289,12 @@ Reflects a positive conditional statement (usually `boolean`) coupled with a cer
```js ```js
function shouldUpdateUrl(url, expectedUrl) { function shouldUpdateUrl(url, expectedUrl) {
return (url !== expectedUrl) return url !== expectedUrl
} }
``` ```
### `min`/`max` ### `min`/`max`
Represent minimum or maximum value. Used when describing boundaries or limits. Represent minimum or maximum value. Used when describing boundaries or limits.
```js ```js
@ -308,7 +314,7 @@ Indicate the previous or the next state of a variable in the current context. Us
```jsx ```jsx
function fetchPosts() { function fetchPosts() {
const prevPosts = this.state.posts const prevPosts = this.state.posts
const fetchedPosts = fetch('...') const fetchedPosts = fetch('...')
const nextPosts = concat(prevPosts, fetchedPosts) const nextPosts = concat(prevPosts, fetchedPosts)
@ -320,14 +326,12 @@ function fetchPosts() {
Like a prefix, variable names can be made singular or plural depending on whether they hold a single value or multiple values. Like a prefix, variable names can be made singular or plural depending on whether they hold a single value or multiple values.
```js ```js
/* Bad */ /* Bad */
const friends = 'Bob'; const friends = 'Bob'
const friend = ['Bob', 'Tony', 'Tanya']; const friend = ['Bob', 'Tony', 'Tanya']
/* Good */ /* Good */
const friend = 'Bob'; const friend = 'Bob'
const friends = ['Bob', 'Tony', 'Tanya']; const friends = ['Bob', 'Tony', 'Tanya']
``` ```