@ioffice/tslint-config-ioffice

iOffice TypeScript Style Guide

Disclaimer: This guide is inspired by the Airbnb JavaScript Style Guide. Most sections we see here will be taken straight from their guide and slowly adapted to the typescript language.

Table of Contents

1. Types
   1. Primitives
   2. Complex
2. Functions
   1. Unused Parameters
3. Classes
4. Arrow Functions
   1. Use Them
5. Blocks
   1. Braces
   2. Cuddled Elses
6. Whitespace
   1. Spaces
   2. In Braces
7. Commas
   1. Leading Trailing
8. Semicolons
   1. Required
9. Modules
   1. Use Them
   2. Single Export

Types

• 1.1 Primitives: When you access a primitive type you work directly on its value.

  • number
  • string
  • boolean
  • null
  • undefined

  These types can be inferred by the typescript compiler and should not explicitly typed.

  Why? Explicit types where they can be easily inferred by the compiler make code more verbose.

  const foo = 1;
  let bar = foo;
  
  bar = 9;
  
  console.log(foo, bar);  // => 1, 9
  

  // bad
  const foo: number = 1;
  
  // good
  let bar: number = foo;
  
  bar = 9;
  
  console.log(foo, bar);  // => 1, 9
  

• 1.2 Complex: When you access a complex type you work on a reference to its value.

  • object
  • array
  • function

  const foo: number[] = [1, 2];
  const bar: number[] = foo;
  
  bar[0] = 9;
  
  console.log(foo[0], bar[0]); // => 9, 9
  

⬆ back to top

Functions

• 2.1 Unused Parameters: Remove them. To prevent them make sure to use noUnusedParameters in your tsconfig.json file.

  We may end up with parameters that are not used when we refactor. If we keep them we risk having incorrect documentation and all sort of confusions.

  In some cases, when creating listeners a function may require a certain signature which will undoubtedly bring us unused parameters. When this is the case simply name the placeholder variables with a leading underscore.

  // bad
  function foo(a, b, c) {
    return a + b;
  }
  
  // good
  function foo(a, b) {
    return a + b;
  }
  

⬆ back to top

Classes

⬆ back to top

Arrow Functions

• 4.1 Use Them: When you must use function expressions (as when passing an anonymous function), use arrow function notation.

  Why? It creates a version of the function that executes in the context of this, which is usually what you want, and is a more concise syntax.

  Why not? If you have a fairly complicated function, you might move that logic out into its own function declaration.

  // bad
  [1, 2, 3].map(function (x) {
    const y = x + 1;
    return x * y;
  });
  
  // good
  [1, 2, 3].map((x) => {
    const y = x + 1;
    return x * y;
  });
  

  // good
  [0, null, 1, null, 2].filter(x => x !== null);
  

⬆ back to top

Blocks

• 5.1 Braces: Use braces with all multi-line blocks.

  // bad
  if (test)
    return false;
  
  // good
  if (test) return false;
  
  // good
  if (test) {
    return false;
  }
  
  // bad
  function foo() { return false; }
  
  // good
  function bar() {
    return false;
  }
  

• 5.2 Cuddled Elses: If you're using multi-line blocks with if and else, put else on the same line as your if block's closing brace.

  // bad
  if (test) {
    thing1();
    thing2();
  }
  else {
    thing3();
  }
  
  // good
  if (test) {
    thing1();
    thing2();
  } else {
    thing3();
  }
  

⬆ back to top

Whitespace

• 6.1 Spaces: Use soft tabs set to 2 spaces.

  // bad
  function foo() {
      const name;
  }
  
  // bad
  function bar() {
   const name;
  }
  
  // good
  function baz() {
    const name;
  }
  

• 6.2 In Braces: Add spaces inside curly braces.

  // bad
  const foo = {clark: 'kent'};
  
  // good
  const foo = { clark: 'kent' };
  

⬆ back to top

Commas

• 7.1 Leading Trailing: Leading commas: Nope.

  // bad
  const story = [
    once
    , upon
    , aTime
  ];
  
  // good
  const story = [
    once,
    upon,
    aTime,
  ];
  
  // bad
  const hero = {
    firstName: 'Ada'
    , lastName: 'Lovelace'
    , birthYear: 1815
    , superPower: 'computers'
  };
  
  // good
  const hero = {
    firstName: 'Ada',
    lastName: 'Lovelace',
    birthYear: 1815,
    superPower: 'computers',
  };
  

⬆ back to top

Semicolons

• 8.1 Required: Yup.

  Why? When JavaScript encounters a line break without a semicolon, it uses a set of rules called Automatic Semicolon Insertion to determine whether or not it should regard that line break as the end of a statement, and (as the name implies) place a semicolon into your code before the line break if it thinks so. ASI contains a few eccentric behaviors, though, and your code will break if JavaScript misinterprets your line break. These rules will become more complicated as new features become a part of JavaScript. Explicitly terminating your statements and configuring your linter to catch missing semicolons will help prevent you from encountering issues.

  // bad - raises exception
  const luke = {}
  const leia = {}
  [luke, leia].forEach(jedi => jedi.father = 'vader')
  
  // bad - raises exception
  const reaction = "No! That's impossible!"
  (async function meanwhileOnTheFalcon() {
    // handle `leia`, `lando`, `chewie`, `r2`, `c3p0`
    // ...
  }())
  
  // bad - returns `undefined` instead of the value on the next line - always happens when `return` is on a line by itself because of ASI!
  function foo() {
    return
      'search your feelings, you know it to be foo'
  }
  
  // good
  const luke = {};
  const leia = {};
  [luke, leia].forEach((jedi) => {
    jedi.father = 'vader';
  });
  
  // good
  const reaction = "No! That's impossible!";
  (async function meanwhileOnTheFalcon() {
    // handle `leia`, `lando`, `chewie`, `r2`, `c3p0`
    // ...
  }());
  
  // good
  function foo() {
    return 'search your feelings, you know it to be foo';
  }
  

⬆ back to top

Modules

• 9.1 Use Them: Always use modules (import/export) over a non-standard module system. You can always transpile to your preferred module system.

  Why? Modules are the future

  // bad
  const iOfficeStyleGuide = require('./iOfficeStyleGuide');
  module.exports = iOfficeStyleGuide.ts;
  
  // ok
  import * as iOfficeStyleGuide from './iOfficeStyleGuide';
  const ts = iOfficeStyleGuide.ts;
  export {
    ts,
  };
  
  // best
  import { ts } from './iOfficeStyleGuide';
  export {
    ts,
  };
  

• 9.2 Single Export: Do not use default exports. Use a single named export which declares all the classes, functions, objects and interfaces that the module is exporting.

  Why? Named imports/exports promote clarity. In addition, current tooling differs on the correct way to handle default imports/exports. Avoiding them all together can help avoid tooling bugs and conflicts.

  Using a single named export allows us to see in one place all the objects that we are exporting.

  // bad
  export class A {}
  export class B {}
  export default A;
  
  // good
  class C {}
  class D {}
  export {
    C,
    D,
  };
  

  // bad
  export default function() {
  }
  
  // good
  function A() {
  }
  export { A };
  

  // good
  function A() {
  }
  export { A };
  

⬆ back to top

License

(The MIT License)

Copyright (c) 2018 iOFFICE

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Amendments

Following Airbnb's advice, we also encourage you to fork this guide and change the rules to fit your team's style guide.

The code provided should make it easy to make adjustments to the examples since they are linted with the tslint configuration. If you do not agree with part of the configuration simply change it, test the guide and make the appropiate changes to it.

Changelog

[0.2.0] - April 27, 2018

• Added tsconfig.core.json. This should provide a configuration related to errors in the code. Other configurations may use it by extending from ./node_modules/@ioffice/tslint-config-ioffice/tsconfig.core.json.

Tslint Rules

• semicolon
• no-interrable-types