Stylistic changes

README.md

@@ -9,6 +9,7 @@ Naming things is hard. Let's make it easier.
 
 ## 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 work.
+
 ```js
 /* Bad */
 const pages_count = 5;
@@ -22,10 +23,12 @@ const shouldUpdate = 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 this variable possesses/does in the most efficient way,
-  * **Intuitive**. Name of the variable should read naturally, as close to common speach as possible
+  * **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
+
 ```js
 /* Bad */
 const a = 5; // "a" could mean anything
@@ -38,6 +41,7 @@ const shouldDisplayPagination = (postsCount > 10);
 ```
 
 * Name should not duplicate the context when the latter is known, and when removing the context from the name does not decrease its readability:
+
 ```js
 class MenuItem {
   /* Method name duplicates the context it is in (which is "MenuItem") */
@@ -48,6 +52,7 @@ class MenuItem {
 }
 ```
 * Name should reflect the expected result:
+
 ```js
 /* Bad */
 const isEnabled = (itemsCount > 3);
@@ -58,14 +63,15 @@ const isDisabled = (itemsCount <= 3);
 return (<Button disabled={isDisabled} />);
 ```
 
-## Pattern
+## HC/LC Pattern
+There is a useful pattern you may follow when naming your methods:
+
 ```
 prefix? + action (A) + high context (HC) + low context? (LC)
 ```
 
-This is not a rule, but rather a useful pattern for naming the variables.
+To illustrate, take a look at how this pattern may be applied in the table below.
 
-### Example
 | Name | Prefix | Action | High context | Low context |
 | ---- | ---- | ------ | ------------ | ----------- |
 | `getPost` | | `get` | `Post` |  |
@@ -73,11 +79,11 @@ This is not a rule, but rather a useful pattern for naming the variables.
 | `handleClickOutside` | | `handle` | `Click` | `Outside` |
 | `shouldDisplayMessage` | `should` | `Display` | `Message`| |
 
-> Keep in mind, that order of the contexts affects the core 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.
-In other words, high context emphasizes the meaning of the variable.
+> **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.
+In other words, **high context emphasizes the meaning of the variable**.
 
 ## Actions
-Chosing proper action name may grant explicit descriptiveness to your methods. This is a good place to start when thinking about a method name.
+Chosing a proper action name may grant explicit descriptiveness to your methods. This is a good place to start when naming your methods.
 
 #### `get`
 Accesses data immediately (i.e. shorthand getter of internal data).
@@ -96,6 +102,7 @@ function fetchPosts(postCount) {
 
 #### `set`
 Declaratively sets a variable with `valueA` to `valueB`.
+
 ```js
 const fruits = 0;
 
@@ -103,46 +110,58 @@ function setFruits(nextFruits) {
   fruits = nextFruits;
 }
 
-setFruits(5); // fruits === 5
+setFruits(5);
+console.log(fruits) // 5
 ```
 
 #### `reset`
-Sets something back to its initial value.
+Sets something back to its initial value or state.
+
 ```js
 const initialFruits = 5;
 const fruits = initialFruits;
-setFruits(10); // fruits === 10
+setFruits(10);
+console.log(fruits); // 10
 
 function resetFruits() {
   fruits = initialFruits;
 }
 
-resetFruits(); // fruits === 5
+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):
+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
 const selectedFilters = ['price', 'availability', 'size'];
 
 function removeFilter(filterName) {
   const filterIndex = selectedFilters.indexOf(filterName);
-  if (filterIndex !== -1) selectedFilters.splice(filterIndex, 1);
+
+  if (filterIndex !== -1) {
+    selectedFilters.splice(filterIndex, 1);
+  }
 
   return selectedFilters;
 }
 ```
 
 #### `delete`
-Completely erazes something from the realms of existance. Imagine you are a blog writer, and you decide to delete one of your posts from the CMS. Once you pressed a shiny "Delete" button you would confirm "Are you sure you want to delete this post?". When you do, you would perform `deletePost` action, not `removePost`.
+Completely erazes something from the realms of existance.
+
+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) {
- const 
+ return database.find({ id }).delete();
 }
 ```
 
 #### `compose`
 Creates a new data from the existing one. Applicable mostly to strings or objects.
+
 ```js
 function composePageUrl(pageName, pageId) {
   return `${pageName.toLowerCase()}-${pageId}`;
@@ -151,6 +170,7 @@ function composePageUrl(pageName, pageId) {
 
 #### `handle`
 Handles a dedicated action. Often used in naming the callback methods.
+
 ```js
 function handleLinkClick(event) {
   event.preventDefault();
@@ -165,6 +185,7 @@ Prefixes enhance variables and methods, indicating an additional meaning behind
 
 #### `is`
 Describes certain characteristic or state of the current context (returns `Boolean`).
+
 ```js
 const color = 'blue';
 const isBlue = (color === 'blue'); // characteristic
@@ -177,6 +198,7 @@ if (isBlue && isPresent) {
 
 #### `min`/`max`
 Represent minimum or maximum value. Handy when describing boundaries or allowed limits.
+
 ```js
 function PostsList() {
   this.minPosts = 3;
@@ -186,6 +208,7 @@ function PostsList() {
 
 #### `has`
 Describes whether the current context possesses a certain value or state.
+
 ```js
 /* Bad */
 const isProductsExist = (productsCount > 0);
@@ -196,7 +219,8 @@ const hasProducts = (productsCount > 0);
 ```
 
 #### `should`
-Reflects a conditional statement (returns `Boolean`) tightly coupled with a certain action.
+Reflects a positive conditional statement (returns `Boolean`) tightly coupled with a certain action.
+
 ```js
 const currentUrl = 'https://dev.com';
 
@@ -206,7 +230,8 @@ function shouldUpdateUrl(url) {
 ```
 
 #### `prev`/`next`
-Indicate the previous and next state of the variable in the current context. Useful for descriptive representation of any kind of the state mutation.
+Indicate the previous and the next state of the variable in the current context. Useful for describing a state mutation.
+
 ```jsx
 function fetchPosts() {
   const prevPosts = this.state.posts;