From c14f44700794d4c20f764687cafbfa9f37f55417 Mon Sep 17 00:00:00 2001 From: Ilya Kantor Date: Mon, 24 Jun 2019 12:57:16 +0300 Subject: [PATCH] fixes --- .../02-coding-style/article.md | 62 ++++++++++++------- 1 file changed, 40 insertions(+), 22 deletions(-) diff --git a/1-js/03-code-quality/02-coding-style/article.md b/1-js/03-code-quality/02-coding-style/article.md index 9f1ca6f3..05f24b6a 100644 --- a/1-js/03-code-quality/02-coding-style/article.md +++ b/1-js/03-code-quality/02-coding-style/article.md @@ -2,11 +2,11 @@ Our code must be as clean and easy to read as possible. -That is actually the art of programming -- to take a complex task and code it in a way that is both correct and human-readable. +That is actually the art of programming -- to take a complex task and code it in a way that is both correct and human-readable. A good code style greatly assists in that. ## Syntax -Here is a cheatsheet with some suggested rules (see below for more details): +Here is a cheat sheet with some suggested rules (see below for more details): ![](code-style.png) ![](figure-bracket-style.png) -In summary: -- For very short code, one line is acceptable. For example: `if (cond) return null`. -- But a separate line for each statement in brackets is usually easier to read. - ### Line Length -No one likes to read a long horizontal line of code. It's best practice to split them up and limit the length of your lines. +No one likes to read a long horizontal line of code. It's best practice to split them. + +For example: +```js +// backtick quotes ` allow to split the string into multiple lines +let str = ` + Ecma International's TC39 is a group of JavaScript developers, + implementers, academics, and more, collaborating with the community + to maintain and evolve the definition of JavaScript. +`; +``` + +And, for `if` statements: + +```js +if ( + id === 123 && + moonPhase === 'Waning Gibbous' && + zodiacSign === 'Libra' +) { + letTheSorceryBegin(); +} +``` The maximum line length should be agreed upon at the team-level. It's usually 80 or 120 characters. @@ -127,15 +145,15 @@ There are two types of indents: A semicolon should be present after each statement, even if it could possibly be skipped. -There are languages where a semicolon is truly optional and it is rarely used. In JavaScript, though, there are cases where a line break is not interpreted as a semicolon, leaving the code vulnerable to errors. +There are languages where a semicolon is truly optional and it is rarely used. In JavaScript, though, there are cases where a line break is not interpreted as a semicolon, leaving the code vulnerable to errors. See more about that in the chapter . -As you become more mature as a programmer, you may choose a no-semicolon style like [StandardJS](https://standardjs.com/). Until then, it's best to use semicolons to avoid possible pitfalls. +If you're an experienced JavaScript programmer, you may choose a no-semicolon code style like [StandardJS](https://standardjs.com/). Otherwise, it's best to use semicolons to avoid possible pitfalls. The majority of developers put semicolons. ### Nesting Levels Try to avoid nesting code too many levels deep. -Sometimes it's a good idea to use the ["continue"](info:while-for#continue) directive in a loop to avoid extra nesting. +For example, in the loop, it's sometimes a good idea to use the ["continue"](info:while-for#continue) directive to avoid extra nesting. For example, instead of adding a nested `if` conditional like this: @@ -197,13 +215,13 @@ function pow(x, n) { } ``` -The second one is more readable because the "edge case" of `n < 0` is handled early on. Once the check is done we can move on to the "main" code flow without the need for additional nesting. +The second one is more readable because the "special case" of `n < 0` is handled early on. Once the check is done we can move on to the "main" code flow without the need for additional nesting. ## Function Placement If you are writing several "helper" functions and the code that uses them, there are three ways to organize the functions. -1. Functions declared above the code that uses them: +1. Declare the functions *above* the code that uses them: ```js // *!*function declarations*/!* @@ -249,7 +267,7 @@ If you are writing several "helper" functions and the code that uses them, there Most of time, the second variant is preferred. -That's because when reading code, we first want to know *what it does*. If the code goes first, then it provides that information. Then, maybe we won't need to read the functions at all, especially if their names are descriptive of what they actually do. +That's because when reading code, we first want to know *what it does*. If the code goes first, then it becomes clear from the start. Then, maybe we won't need to read the functions at all, especially if their names are descriptive of what they actually do. ## Style Guides @@ -257,7 +275,7 @@ A style guide contains general rules about "how to write" code, e.g. which quote When all members of a team use the same style guide, the code looks uniform, regardless of which team member wrote it. -Of course, a team can always write their own style guide. Most of the time though, there's no need to. There are many existing tried and true options to choose from, so adopting one of these is usually your best bet. +Of course, a team can always write their own style guide, but usually there's no need to. There are many existing guides to choose from. Some popular choices: @@ -267,15 +285,15 @@ Some popular choices: - [StandardJS](https://standardjs.com/) - (plus many more) -If you're a novice developer, start with the cheatsheet at the beginning of this chapter. Once you've mastered that you can browse other style guides to pick up common principles and decide which one you like best. +If you're a novice developer, start with the cheat sheet at the beginning of this chapter. Then you can browse other style guides to pick up more ideas and decide which one you like best. ## Automated Linters -Linters are tools that can automatically check the style of your code and make suggestions for refactoring. +Linters are tools that can automatically check the style of your code and make improving suggestions. -The great thing about them is that style-checking can also find some bugs, like typos in variable or function names. Because of this feature, installing a linter is recommended even if you don't want to stick to one particular "code style". +The great thing about them is that style-checking can also find some bugs, like typos in variable or function names. Because of this feature, using a linter is recommended even if you don't want to stick to one particular "code style". -Here are the most well-known linting tools: +Here are some well-known linting tools: - [JSLint](http://www.jslint.com/) -- one of the first linters. - [JSHint](http://www.jshint.com/) -- more settings than JSLint. @@ -317,8 +335,8 @@ Also certain IDEs have built-in linting, which is convenient but not as customiz ## Summary -All syntax rules described in this chapter (and in the style guides referenced) aim to increase the readability of your code, but all of them are debatable. +All syntax rules described in this chapter (and in the style guides referenced) aim to increase the readability of your code. All of them are debatable. -When we think about writing "better" code, the questions we should ask are, "What makes the code more readable and easier to understand?" and "What can help us avoid errors?" These are the main things to keep in mind when choosing and debating code styles. +When we think about writing "better" code, the questions we should ask ourselves are: "What makes the code more readable and easier to understand?" and "What can help us avoid errors?" These are the main things to keep in mind when choosing and debating code styles. Reading popular style guides will allow you to keep up to date with the latest ideas about code style trends and best practices.