diff --git a/README.md b/README.md index 80b4537..54e608d 100644 --- a/README.md +++ b/README.md @@ -5,99 +5,91 @@

# 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 -* [Guidelines](#guidelines) -* [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. +## 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. ```js /* Bad */ -const pages_count = 5; -const shouldUpdate = true; +const pages_count = 5 +const shouldUpdate = true /* Good */ -const pagesCount = 5; -const shouldUpdate = true; +const pagesCount = 5 +const shouldUpdate = true /* Good as well */ -const pages_count = 5; -const should_update = true; +const pages_count = 5 +const should_update = true ``` -* Name, whether of a variable, method, or something else, should be *short*, *descriptive* and *intuitive*: - * **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, - * **Intuitive**. Name of the variable should read naturally, as close to the common speach as possible +## S-I-D + +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 + * **Descriptive**. Name must reflect what it does/possesses in the most efficient way, ```js /* Bad */ -const a = 5; // "a" could mean anything -const isPaginatable = (postsCount > 10); // "Paginatable" sounds extremely unnatural -const shouldPaginatize = (postsCount > 10); // Made up verbs are so much fun! +const a = 5 // "a" could mean anything +const isPaginatable = (postsCount > 10) // "Paginatable" sounds extremely unnatural +const shouldPaginatize = (postsCount > 10) // Made up verbs are so much fun! /* Good */ -const postsCount = 5; -const shouldDisplayPagination = (postsCount > 10); +const postsCount = 5 +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 /* Bad */ -const onItmClck = () => {}; +const onItmClk = () => {} /* 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 class MenuItem { - /* Method name duplicates the context it is in (which is "MenuItem") */ + /* Method name duplicates the context (which is "MenuItem") */ handleMenuItemClick = (event) => { ... } - /* This way it reads as MenuItem.handleClick() */ + /* Reads nicely as `MenuItem.handleClick()` */ handleClick = (event) => { ... } } ``` -* Name should reflect the expected result: -```js +## Reflect expected result + +A name should reflect the expected result. + +```jsx /* Bad */ -const isEnabled = (itemsCount > 3); -return (