blob: 764861c40023f9d7cbc1cc11c54c7fce70bc6b8d (
plain) (
tree)
|
|
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<meta name="dcterms.date" content="2018-09-21" />
<title>Style Guide</title>
<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
</style>
<style type="text/css">
a.sourceLine { display: inline-block; line-height: 1.25; }
a.sourceLine { pointer-events: none; color: inherit; text-decoration: inherit; }
a.sourceLine:empty { height: 1.2em; position: absolute; }
.sourceCode { overflow: visible; }
code.sourceCode { white-space: pre; position: relative; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
code.sourceCode { white-space: pre-wrap; }
a.sourceLine { text-indent: -1em; padding-left: 1em; }
}
pre.numberSource a.sourceLine
{ position: relative; }
pre.numberSource a.sourceLine:empty
{ position: absolute; }
pre.numberSource a.sourceLine::before
{ content: attr(data-line-number);
position: absolute; left: -5em; text-align: right; vertical-align: baseline;
border: none; pointer-events: all;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
a.sourceLine::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
</style>
<link rel="stylesheet" href="assets/lib/bootstrap/bootstrap.min.css">
<link rel="stylesheet" href="assets/lib/fontawesome/css/font-awesome.min.css">
<link rel="stylesheet" href="assets/stylesheets/main.css">
</head>
<body>
<header class="container">
<div style="text-align: center;">
<h1>Style Guide</h1>
<p class="subtitle">Software Engineering at Driver</p>
<nav class="my-4">
<a class="btn btn-light" href="css.html">
<img src="assets/images/css.svg" width="16px" class="img-fluid">
CSS
</a>
<a class="btn btn-light" href="git.html">
<img src="assets/images/git.png" width="16px" class="img-fluid">
Git
</a>
<a class="btn btn-light" href="html.html">
<img src="assets/images/html5.svg" width="16px" class="img-fluid">
HTML
</a>
<a class="btn btn-light" href="javascript.html">
<img src="assets/images/javascript.png" width="16px" class="img-fluid">
JavaScript
</a>
<a class="btn btn-light" href="scala.html">
<img src="assets/images/scala.png" width="16px" class="img-fluid">
Scala
</a>
<a class="btn btn-light" href="shell-script.html">
<img src="assets/images/bash.svg" width="16px" class="img-fluid">
Shell Script
</a>
</nav>
</div>
</header>
<div class="container">
This guide recommends stylistic and architectural best
practices, designed to make your code easier for others to
understand. It offers <em>guidelines</em> not <em>rules</em>,
and there are situations in which the advice offered
should be actively ignored.
<hr>
</div>
<main class="container">
<h2 id="javascript">JavaScript</h2>
<ul>
<li><p>Type with flow</p></li>
<li><p>Style with <a href="https://prettier.io/">prettier</a> (<a href="#prettier">see section below</a>)</p></li>
<li><p>Lint with eslint and use <code>eslint:recommended</code> at a minimum</p></li>
<li><p>Test with <a href="https://facebook.github.io/jest/">jest</a> and enzyme</p></li>
<li><p>2 spaces (instead of tabs)</p></li>
<li><p>Promises (not callbacks)</p></li>
<li><p>No <a href="https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841">decorators</a></p></li>
<li><p>No <a href="https://mobx.js.org/">mobx</a></p></li>
<li><p>Place tests alongside the file(s) it tests (not in a separate directory)</p></li>
<li><p>End test files with <code>.test.js</code></p></li>
</ul>
<h3 id="reactredux">React/Redux</h3>
<ul>
<li><p>Lint with <a href="https://github.com/palantir/tslint-react"><code>tslint-react</code></a> or eslintβs <a href="https://github.com/yannickcr/eslint-plugin-react"><code>plugin:react/recommended</code></a> at a minimum.</p></li>
<li><p>No unnecessary and empty <code><div></code>βs</p></li>
<li><p>If <code>this.props.<variable name></code> is used more than once, dereference it at the top of <code>render</code>.</p></li>
<li><p>Extract variables used in <code>render()</code> to the top of <code>render()</code></p></li>
<li><p>API calls should lie in a testable file outside of components.</p></li>
<li><p>Components should not wait for promises to resolve, instead listen on props via reduxβ <code>mapStateToProps()</code>.</p></li>
<li><p>Declare and export components in separate places (otherwise the web inspector cannot name components properly)</p></li>
</ul>
<h3 id="flowtype">Flowtype</h3>
<ul>
<li><p>Any types used in more than one file should be placed in <code>src/types.js</code></p></li>
<li><p>Add flow linting via <a href="https://github.com/gajus/eslint-plugin-flowtype">eslint-plugin-flowtype</a></p></li>
<li><p>Disallow β<code>any</code>β with <a href="https://github.com/gajus/eslint-plugin-flowtype#no-weak-types">eslint no-weak-types</a> (use β<code>Obect</code>β and β<code>Function</code>β to cover complicated use-cases)</p></li>
<li><p>In components which use <code>mapStateToProps</code>, separate <code>OwnProps</code> from <code>ConnectedProps</code> into separate types. Join them with <code>type Props = OwnProps & ConnectedProps</code>. In addition, if using <code>mapDispatchToProps</code>, create a type <code>DispatchProps</code> and join that with <code>Props</code>.</p></li>
</ul>
<h3 id="π£π’-typescript-π£π’">π£π’ TypeScript π£π’</h3>
<ul>
<li><p>Lint with <a href="https://github.com/palantir/tslint"><code>tslint:recommended</code></a> at a minimum.</p></li>
<li><p>No implicit any (type everything thatβs not inferable)</p></li>
<li><p>Any variable declared without an initial value should be typed</p></li>
</ul>
<h3 id="prettier">Prettier</h3>
<p>Add the following to <code>package.json</code>:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode json"><code class="sourceCode json"><a class="sourceLine" id="cb1-1" data-line-number="1"> <span class="er">"prettier":</span> <span class="fu">{</span></a>
<a class="sourceLine" id="cb1-2" data-line-number="2"> <span class="dt">"overrides"</span><span class="fu">:</span> <span class="ot">[</span></a>
<a class="sourceLine" id="cb1-3" data-line-number="3"> <span class="fu">{</span></a>
<a class="sourceLine" id="cb1-4" data-line-number="4"> <span class="dt">"files"</span><span class="fu">:</span> <span class="ot">[</span><span class="st">"*.js"</span><span class="ot">,</span> <span class="st">"*.scss"</span><span class="ot">,</span> <span class="st">"*.css"</span><span class="ot">,</span> <span class="st">"*.pcss"</span><span class="ot">]</span><span class="fu">,</span></a>
<a class="sourceLine" id="cb1-5" data-line-number="5"> <span class="dt">"options"</span><span class="fu">:</span> <span class="fu">{</span></a>
<a class="sourceLine" id="cb1-6" data-line-number="6"> <span class="dt">"singleQuote"</span><span class="fu">:</span> <span class="kw">true</span><span class="fu">,</span></a>
<a class="sourceLine" id="cb1-7" data-line-number="7"> <span class="dt">"trailingComma"</span><span class="fu">:</span> <span class="st">"all"</span></a>
<a class="sourceLine" id="cb1-8" data-line-number="8"> <span class="fu">}</span></a>
<a class="sourceLine" id="cb1-9" data-line-number="9"> <span class="fu">}</span></a>
<a class="sourceLine" id="cb1-10" data-line-number="10"> <span class="ot">]</span></a>
<a class="sourceLine" id="cb1-11" data-line-number="11"> <span class="fu">}</span></a></code></pre></div>
<p>The following information about prettier is better described on the prettier documentation <a href="https://prettier.io/docs/en/precommit.html#option-1-lint-staged-https-githubcom-okonet-lint-staged">here</a>. Use <code>lint-staged</code> to auto-call prettier in a <code>precommit</code> β<code>script</code>β:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode json"><code class="sourceCode json"><a class="sourceLine" id="cb2-1" data-line-number="1"> <span class="er">"lint-staged":</span> <span class="fu">{</span></a>
<a class="sourceLine" id="cb2-2" data-line-number="2"> <span class="dt">"src/**/*.scss"</span><span class="fu">:</span> <span class="ot">[</span><span class="st">"prettier --parser scss --write"</span><span class="ot">,</span> <span class="st">"git add"</span><span class="ot">]</span><span class="fu">,</span></a>
<a class="sourceLine" id="cb2-3" data-line-number="3"> <span class="dt">"src/**/*.{js,css}"</span><span class="fu">:</span> <span class="ot">[</span><span class="st">"prettier --parser flow --write"</span><span class="ot">,</span> <span class="st">"git add"</span><span class="ot">]</span><span class="fu">,</span></a>
<a class="sourceLine" id="cb2-4" data-line-number="4"> <span class="dt">"nightwatch/**/*.js"</span><span class="fu">:</span> <span class="ot">[</span><span class="st">"prettier --write"</span><span class="ot">,</span> <span class="st">"git add"</span><span class="ot">]</span></a>
<a class="sourceLine" id="cb2-5" data-line-number="5"> <span class="fu">}</span></a></code></pre></div>
<h3 id="npm">Npm</h3>
<ul>
<li>Support the following <code>script</code>βs in your root <code>package.json</code>:</li>
</ul>
<ol type="1">
<li><code>βwatchβ</code>: Starts the dev server</li>
<li><code>βbuildβ</code>: Builds static assets (if they exist) β<code>/src</code>β -> β<code>/build</code>β</li>
<li><code>βtestβ</code>: Runs all tests (linting first, then unit tests)</li>
</ol>
</main>
<footer class="small mt-6 mb-1">
<span class="date">2018-09-21</span>
| <a href="https://github.com/drivergroup/best-practices/blob/master/guides/javascript.md" style="display: inline-block;"><i class="fa fa-github"></i> Edit on GitHub</a>
</footer>
</body>
</html>
|
