From 1ef2ec2ffbd9f05ec32b0233bcb31341cd9d9edc Mon Sep 17 00:00:00 2001 From: Kyle Martin Date: Tue, 15 Jan 2019 19:24:30 +1300 Subject: [PATCH] minor readability changes to best practice names --- README.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 3708f1eb..944d6613 100644 --- a/README.md +++ b/README.md @@ -150,11 +150,11 @@ Read in a different language: [![CN](/assets/flags/CN.png)**CN**](/README.chines

-## ![✔] 2.6 Shut the process gracefully when a stranger comes to town +## ![✔] 2.6 Shutdown the process gracefully when a stranger comes to town -**TL;DR:** When an unknown error occurs (a developer error, see best practice number #3)- there is uncertainty about the application healthiness. A common practice suggests restarting the process carefully using a ‘restarter’ tool like Forever and PM2 +**TL;DR:** When an unknown error occurs (a developer error, see best practice 2.3) - there is uncertainty about the application healthiness. A common practice suggests restarting the process carefully using a process management tool like Forever or PM2 -**Otherwise:** When an unfamiliar exception is caught, some object might be in a faulty state (e.g an event emitter which is used globally and not firing events anymore due to some internal failure) and all future requests might fail or behave crazily +**Otherwise:** When an unfamiliar exception occurs, some object might be in a faulty state (e.g an event emitter which is used globally and not firing events anymore due to some internal failure) and all future requests might fail or behave crazily 🔗 [**Read More: shutting the process**](/sections/errorhandling/shuttingtheprocess.md) @@ -222,9 +222,9 @@ Read in a different language: [![CN](/assets/flags/CN.png)**CN**](/README.chines

-## ![✔] 3.2 Node.js Specific Plugins +## ![✔] 3.2 Node.js specific plugins -**TL;DR:** On top of ESLint standard rules that cover vanilla JS only, add Node-specific plugins like [eslint-plugin-node](https://www.npmjs.com/package/eslint-plugin-node), [eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha) and [eslint-plugin-node-security](https://www.npmjs.com/package/eslint-plugin-security) +**TL;DR:** On top of ESLint standard rules that cover vanilla JavaScript, add Node.js specific plugins like [eslint-plugin-node](https://www.npmjs.com/package/eslint-plugin-node), [eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha) and [eslint-plugin-node-security](https://www.npmjs.com/package/eslint-plugin-security) **Otherwise:** Many faulty Node.js code patterns might escape under the radar. For example, developers might require(variableAsPath) files with a variable given as path which allows attackers to execute any JS script. Node.js linters can detect such patterns and complain early @@ -232,7 +232,7 @@ Read in a different language: [![CN](/assets/flags/CN.png)**CN**](/README.chines ## ![✔] 3.3 Start a Codeblock's Curly Braces on the Same Line -**TL;DR:** The opening curly braces of a code block should be in the same line of the opening statement +**TL;DR:** The opening curly braces of a code block should be on the same line as the opening statement ### Code Example @@ -279,7 +279,7 @@ const count = 2 // it tries to run 2(), but 2 is not a function

-## ![✔] 3.5 Name Your Functions +## ![✔] 3.5 Name your functions **TL;DR:** Name all functions, including closures and callbacks. Avoid anonymous functions. This is especially useful when profiling a node app. Naming all functions will allow you to easily understand what you're looking at when checking a memory snapshot @@ -287,7 +287,7 @@ const count = 2 // it tries to run 2(), but 2 is not a function

-## ![✔] 3.6 Naming conventions for variables, constants, functions and classes +## ![✔] 3.6 Use naming conventions for variables, constants, functions and classes **TL;DR:** Use **_lowerCamelCase_** when naming constants, variables and functions and **_UpperCamelCase_** (capital first letter as well) when naming classes. This will help you to easily distinguish between plain variables/functions, and classes that require instantiation. Use descriptive names, but try to keep them short @@ -321,7 +321,7 @@ function doSomething() {}

-## ![✔] 3.8 Requires come first, and not inside functions +## ![✔] 3.8 Require modules first, not inside functions **TL;DR:** Require modules at the beginning of each file, before and outside of any functions. This simple best practice will not only help you easily and quickly tell the dependencies of a file right at the top but also avoids a couple of potential problems @@ -329,7 +329,7 @@ function doSomething() {}

-## ![✔] 3.9 Do Require on the folders, not directly on the files +## ![✔] 3.9 Require modules by folders, opposed to the files directly **TL;DR:** When developing a module/library in a folder, place an index.js file that exposes the module's internals so every consumer will pass through it. This serves as an 'interface' to your module and eases @@ -389,7 +389,7 @@ All statements above will return false if used with `===`

-## ![✔] 3.12 Use Fat (=>) Arrow Functions +## ![✔] 3.12 Use arrow function expressions (=>) **TL;DR:** Though it's recommended to use async-await and avoid function parameters when dealing with older API that accept promises or callbacks - arrow functions make the code structure more compact and keep the lexical context of the root function (i.e. 'this') @@ -525,7 +525,7 @@ All statements above will return false if used with `===` ## ![✔] 5.5. Guard process uptime using the right tool -**TL;DR:** The process must go on and get restarted upon failures. For simple scenarios, ‘restarter’ tools like PM2 might be enough but in today ‘dockerized’ world – a cluster management tools should be considered as well +**TL;DR:** The process must go on and get restarted upon failures. For simple scenarios, process management tools like PM2 might be enough but in today ‘dockerized’ world, cluster management tools should be considered as well **Otherwise:** Running dozens of instances without a clear strategy and too many tools together (cluster management, docker, PM2) might lead to a DevOps chaos @@ -555,7 +555,7 @@ All statements above will return false if used with `===` ## ![✔] 5.8. Discover errors and downtime using APM products -**TL;DR:** Monitoring and performance products (a.k.a APM) proactively gauge codebase and API so they can auto-magically go beyond traditional monitoring and measure the overall user-experience across services and tiers. For example, some APM products can highlight a transaction that loads too slow on the end-users side while suggesting the root cause +**TL;DR:** Application monitoring and performance products (a.k.a APM) proactively gauge codebase and API so they can auto-magically go beyond traditional monitoring and measure the overall user-experience across services and tiers. For example, some APM products can highlight a transaction that loads too slow on the end-users side while suggesting the root cause **Otherwise:** You might spend great effort on measuring API performance and downtimes, probably you’ll never be aware which is your slowest code parts under real-world scenario and how these affects the UX @@ -593,7 +593,7 @@ All statements above will return false if used with `===`

-## ![✔] 5.12. Be stateless, kill your Servers almost every day +## ![✔] 5.12. Be stateless, kill your servers almost every day **TL;DR:** Store any type of data (e.g. users session, cache, uploaded files) within external data stores. Consider ‘killing’ your servers periodically or use ‘serverless’ platform (e.g. AWS Lambda) that explicitly enforces a stateless behavior @@ -613,7 +613,7 @@ All statements above will return false if used with `===`

-## ![✔] 5.14. Assign ‘TransactionId’ to each log statement +## ![✔] 5.14. Assign a transaction id to each log statement **TL;DR:** Assign the same identifier, transaction-id: {some value}, to each log entry within a single request. Then when inspecting errors in logs, easily conclude what happened before and after. Unfortunately, this is not easy to achieve in Node due to its async nature, see code examples inside