Skip to content

Commit

Permalink
docs(style): add style preference for writing code explicitly (#4879)
Browse files Browse the repository at this point in the history
* docs(style): add style preference for explicit features

* docs(style): update phrasing

* docs(style): add explicit table example for section

* docs(style): move table block to beginning of section
  • Loading branch information
joshblack authored Dec 16, 2019
1 parent 610f69a commit 5402407
Showing 1 changed file with 66 additions and 0 deletions.
66 changes: 66 additions & 0 deletions docs/style.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,9 @@ row before the </tbody></table> line.
## Table of Contents

- [Introduction](#introduction)
- [JavaScript](#javascript)
- [Style](#style)
- [Be explicit](#be-explicit)
- [React](#react)
- [Guidelines](#guidelines)
- [Writing a component](#writing-a-component)
Expand Down Expand Up @@ -90,6 +93,69 @@ code:
_Inspired by
[Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8)_

## JavaScript

### Style

#### Be explicit

<table>
<thead><tr><th>Unpreferred</th><th>Preferred</th></tr></thead>
<tbody>
<tr><td>

```jsx
const add = (a, b) => a + b;
```

</td><td>

```jsx
const add = (a, b) => {
return a + b;
};
```

</td></tr>
</tbody></table>

Certain features in JavaScript have implicit behavior. One of these that we see
most often is the implicit return behavior of arrow function expressions, for
example:

```js
const add = (a, b) => a + b;
```

We've found that, while this style is terse and compact, it can be at odds with
the fact that code is revisited often and that developers need to peak inside
sometimes to see what is going on. For example, if we needed to debug a specific
value in the function above then we would go through the following steps:

```js
// Step 1. The code as originally authored
const add = (a, b) => a + b;

// Step 2. Update the code to no longer use the implicit return
const add = (a, b) => {
return a + b;
};

// Step 3. Add any debugging code or ways to introspect its values
const add = (a, b) => {
console.log(a);
return a + b;
};

// Step 4. Undo these changes and bring back to original format
const add = (a, b) => a + b;
```

If instead we had written this code without the implicit return then we would
have saved three out of the four steps above. As a result, we tend to favor
being explicit in how JavaScript is written instead of relying on implicit
behavior.

## React

### Guidelines
Expand Down

0 comments on commit 5402407

Please sign in to comment.