Skip to content

Commit

Permalink
Adjust grammar in Coding Style page
Browse files Browse the repository at this point in the history
  • Loading branch information
Cat McLoughlin committed Oct 22, 2018
1 parent dac2e71 commit b7bf483
Showing 1 changed file with 54 additions and 64 deletions.
118 changes: 54 additions & 64 deletions 1-js/03-code-quality/02-coding-style/article.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
# Coding style
# Coding Style

Our code must be as clean and easy to read as possible.

That is actually an art of programming -- to take a complex task and code it in a way that is both correct and human-readable.

One thing to help is the good code style.
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.

## Syntax

A cheatsheet with the rules (more details below):
Here is a cheatsheet with some suggested rules (see below for more details):

![](code-style.png)
<!--
Expand Down Expand Up @@ -38,13 +36,13 @@ if (n < 0) {

Now let's discuss the rules and reasons for them in detail.

Nothing is "carved in stone" here. Everything is optional and can be changed: these are coding rules, not religious dogmas.

### Curly braces
```warn header="Irony Detected"
Nothing is set in stone here. These are style preferences, not religious dogmas.
```

In most JavaScript projects curly braces are written on the same line as the corresponding keyword, not on the new line, a so-called "Egyptian" style. There's also a space before an opening bracket.
### Curly Braces

Like this:
In most JavaScript projects curly braces are written in "Egyptian" style with the opening brace on the same line as the corresponding keyword -- not on a new line. There should also be a space before the opening bracket, like this:

```js
if (condition) {
Expand All @@ -56,7 +54,7 @@ if (condition) {

A single-line construct is an important edge case. Should we use brackets at all? If yes, then where?

Here are the annotated variants, so you can judge about their readability on your own:
Here are the annotated variants so you can judge their readability for yourself:

<!--
```js no-beautify
Expand All @@ -74,21 +72,21 @@ if (n < 0) {
-->
![](figure-bracket-style.png)

As a summary:
- For a really short code, one line is acceptable: like `if (cond) return null`.
- But a separate line for each statement in brackets is usually better.
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
### Line Length

The maximal line length should be limited. No one likes to eye-follow a long horizontal line. It's better to split it.
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.

The maximal line length is agreed on the team-level. It's usually 80 or 120 characters.
The maximum line length should be agreed upon at the team-level. It's usually 80 or 120 characters.

### Indents

There are two types of indents:

- **A horizontal indent: 2(4) spaces.**
- **Horizontal indents: 2 or 4 spaces.**

A horizontal indentation is made using either 2 or 4 spaces or the "Tab" symbol. Which one to choose is an old holy war. Spaces are more common nowadays.

Expand All @@ -107,9 +105,9 @@ There are two types of indents:
}
```

- **A vertical indent: empty lines for splitting code into logical blocks.**
- **Vertical indents: empty lines for splitting code into logical blocks.**

Even a single function can often be divided in logical blocks. In the example below, the initialization of variables, the main loop and returning the result are split vertically:
Even a single function can often be divided into logical blocks. In the example below, the initialization of variables, the main loop and returning the result are split vertically:

```js
function pow(x, n) {
Expand All @@ -125,21 +123,21 @@ There are two types of indents:

Insert an extra newline where it helps to make the code more readable. There should not be more than nine lines of code without a vertical indentation.

### A semicolon
### Semicolons

A semicolon should be present after each statement. Even if it could possibly be skipped.
A semicolon should be present after each statement, even if it could possibly be skipped.

There are languages where a semicolon is truly optional. It's rarely used there. But in JavaScript there are few cases when a line break is sometimes not interpreted as a semicolon. That leaves a place for programming 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.

As you become more mature as a programmer, you may choose a no-semicolon style, like [StandardJS](https://standardjs.com/), but that's only when you know JavaScript well and understand possible pitfalls.
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.

### Nesting levels
### Nesting Levels

There should not be too many 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 the loop to evade extra nesting in `if(..) { ... }`:
Sometimes it's a good idea to use the ["continue"](info:while-for#continue) directive in a loop to avoid extra nesting.
Instead of:
For example, instead of adding a nested `if` conditional like this:
```js
for (let i = 0; i < 10; i++) {
Expand All @@ -162,7 +160,7 @@ A similar thing can be done with `if/else` and `return`.
For example, two constructs below are identical.
The first one:
Option 1:
```js
function pow(x, n) {
Expand All @@ -180,7 +178,7 @@ function pow(x, n) {
}
```
And this:
Option 2:
```js
function pow(x, n) {
Expand All @@ -199,13 +197,13 @@ function pow(x, n) {
}
```
...But the second one is more readable, because the "edge case" of `n < 0` is handled early on, and then we have the "main" code flow, without an additional nesting.
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.
## Functions below the code
## Function Placement
If you are writing several "helper" functions and the code to use them, then there are three ways to place them.
If you are writing several "helper" functions and the code that uses them, there are three ways to organize the functions.
1. Functions above the code that uses them:
1. Functions declared above the code that uses them:
```js
// *!*function declarations*/!*
Expand Down Expand Up @@ -235,7 +233,6 @@ If you are writing several "helper" functions and the code to use them, then the
walkAround();
// --- *!*helper functions*/!* ---
function createElement() {
...
}
Expand All @@ -248,55 +245,54 @@ If you are writing several "helper" functions and the code to use them, then the
...
}
```
3. Mixed: a function is described where it's first used.
3. Mixed: a function is declared where it's first used.

Most of time, the second variant is preferred.

That's because when reading a code, we first want to know "what it does". If the code goes first, then it provides that information. And then maybe we won't need to read functions at all, especially if their names are adequate to what they're doing.
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.

## Style guides
## Style Guides

A style guide contains general rules about "how to write": which quotes to use, how many spaces to indent, where to put line breaks, etc. A lot of minor things.
A style guide contains general rules about "how to write" code, e.g. which quotes to use, how many spaces to indent, where to put line breaks, etc. A lot of minor things.

In total, when all members of a team use the same style guide, the code looks uniform. No matter who of the team wrote it, it's still the same style.
When all members of a team use the same style guide the code tends looks uniform, regardless of which team member wrote it.

Surely, a team may think out a style guide themselves. But as of now, there's no need to. There are many tried, worked-out style guides, which are easy to adopt.
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.
For instance:
Some popular choices:
- [Google JavaScript Style Guide](https://google.github.io/styleguide/javascriptguide.xml)
- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)
- [Idiomatic.JS](https://github.com/rwaldron/idiomatic.js)
- [StandardJS](https://standardjs.com/)
- (there are more)
- (plus many more)
If you're a novice developer, then you could start with the cheatsheet above in the chapter, and later browse the style guides to pick up the common principles and maybe choose one.
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.
## Automated linters
## Automated Linters
There are tools that can check the code style automatically. They are called "linters".
Linters are tools that can automatically check the style of your code and make suggestions for refactoring.
The great thing about them is that style-checking also finds some bugs, like a typo in a variable or function name.
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".

So it's recommended to install one, even if you don't want to stick to a "code style". They help to find typos -- and that's already good enough.

Most well-known tools are:
Here are the most well-known linting tools:

- [JSLint](http://www.jslint.com/) -- one of the first linters.
- [JSHint](http://www.jshint.com/) -- more settings than JSLint.
- [ESLint](http://eslint.org/) -- probably the newest one.

All of them can do the job. The author uses [ESLint](http://eslint.org/).

Most linters are integrated with editors: just enable the plugin in the editor and configure the style.
Most linters are integrated with many popular editors: just enable the plugin in the editor and configure the style.

For instance, for ESLint you should do the following:

1. Install [Node.JS](https://nodejs.org/).
2. Install ESLint with the command `npm install -g eslint` (npm is a JavaScript package installer).
3. Create a config file named `.eslintrc` in the root of your JavaScript project (in the folder that contains all your files).
4. Install/enable the plugin for your editor that integrates with ESLint. The majority of editors have one.

Here's an example of `.eslintrc`:
Here's an example of an `.eslintrc` file:
```js
{
Expand All @@ -313,22 +309,16 @@ Here's an example of `.eslintrc`:
}
```
Here the directive `"extends"` denotes that we base on the "eslint:recommended" set of settings, and then we specify our own.
Then install/enable the plugin for your editor that integrates with ESLint. The majority of editors have it.
It is possible to download style rule sets from the web and extend them instead. See <http://eslint.org/docs/user-guide/getting-started> for more details about installation.
Using a linter has a great side-effect: linters catch typos. For instance, when an undefined variable is accessed, a linter detects it and (if integrated with an editor) highlights it. In most cases that's a mistype. So we can fix it right ahead.
Here the directive `"extends"` denotes that the configuration is based on the "eslint:recommended" set of settings. After that, we specify our own.
For that reason even if you're not concerned about styles, using a linter is highly recommended.
It is also possible to download style rule sets from the web and extend them instead. See <http://eslint.org/docs/user-guide/getting-started> for more details about installation.
Also certain IDEs support built-in linting, that also may be good, but not so tunable as ESLint.
Also certain IDEs have built-in linting, which is convenient but not as customizable as ESLint.
## Summary
All syntax rules from this chapter and the style guides aim to increase readability, so 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, but all of them are debatable.
When we think about "how to write better?", the sole criterion is "what makes the code more readable and easier to understand? what helps to avoid errors?" That's the main thing to keep in mind when choosing the style or discussing which one is better.
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.
Read style guides to see the latest ideas about that and follow those that you find the best.
Reading popular style guides will allow you to keep up to date with the latest ideas about code style trends and best practices.

0 comments on commit b7bf483

Please sign in to comment.