Explain Linting Decisions in Documentation

[RichardLitt]

What

I want a place describing rationale behind linting decisions in the documentation.

Background

I just went to ipfs/community to the js-guidelines to look for a place to add a note about not nesting deps too deeply. There isn't a good place to put this. I think this isn't great; we should be able to explain our linting decisions in aegir, somewhere, if only in this README, or in the js-guidelines README.

It would be great if we could add a section for each linting decision, or each major design decision. I am 100% ok with pointing to issues in brief sentences, but I think this should exist. Otherwise, I don't know how to find the rationale for something if I find it controversial.

[dignifiedquire]

I'm okay with doing this for the rules that we have that extend standard, but for those that are part of standard I'd defer to their readme & issue tracker, rather than replicating all of that.

[dignifiedquire]

@RichardLitt I wrote a sloppy version of the rules we use below, as annotations to the config, it would be awesome if you could take that and put it into a format other humans enjoy to consume it. <3

# we like standard, for details see https://github.com/ferros/standard
extends: standard
parserOptions:
# we need this to enforce 'use strict'
  sourceType: 'script'
rules:
# not using strict mode, has bitten as in multiple occasions, so we enforce it now
  strict: [2, 'safe']
# @diasdavid is happy when there are curlys
  curly: 'error'
# we generally use only let and const in our code, using this avoids accidental odd usage of vars
  block-scoped-var: 2
# don't let your code get too complex, only a warning though
  complexity: 1
# always provide a default case in your switch statements to avoid errors
  default-case: 2
# please write foo.bar, not foo['bar']
  dot-notation: 1
# if you use for in, warn if no guard is used to avoid accidental iterations
  guard-for-in: 1
# make sure line breaks are good
  linebreak-style: [1, 'unix']
# don't leave accidental alerts lying around
  no-alert: 2
# case statements are no blocks, so please don't declare variables in them
  no-case-declarations: 2
# don't leave accidental console.logs lying around
  no-console: 1
# usually a typo or bug if this happens
  no-constant-condition: 2
# continues should be used rarely, let's warn if they happen 
  no-continue: 1
# make regexes a little easier to read
  no-div-regex: 2
# empty blocks are usually a bug
  no-empty: 1
# avoid accidental mistakes when doing destructuring
  no-empty-pattern: 2
# even less semicolons (not sure we need this, but it doesn't do any harm either)
  no-extra-semi: 2
# make your type casts explicit, yes even in JavaScript
  no-implicit-coercion: 2
# please do not use labels, nobody knows how they work 
  no-labels: 2
# creating functions in loops is a sure way to make code slow 
  no-loop-func: 2
# ternaries (?:) are hard to read the longer they become, you probably shouldn't start nesting them
  no-nested-ternary: 1
# too close to eval, and there shouldn't be any need for it
  no-script-url: 2
# make all those TODOs you wrote visible so the don't get forgotten
  no-warning-comments: 1
# quote props only if you have to
  quote-props: [2, 'as-needed']
# guard against buggy generators 
  require-yield: 2
# nesting of callbacks can get very hairy, so enforcing a max nesting level 
  max-nested-callbacks: [2, 4]
# same goes for code indentation, we are not in inception here  
  max-depth: [2, 4]
# we use jsdoc, so we want to make sure that if it's there, it is valid
  valid-jsdoc: [2, {'requireParamDescription': false, 'requireReturnDescription': false}]

[daviddias]

@diasdavid is happy when there are curlys
curly: 'error'

• https://blog.codecentric.de/en/2014/02/curly-braces/
• http://embeddedgurus.com/barr-code/2014/03/apples-gotofail-ssl-security-bug-was-easily-preventable/

[RichardLitt]

@RichardLitt I wrote a sloppy version of the rules we use below, as annotations to the config, it would be awesome if you could take that and put it into a format other humans enjoy to consume it. <3

I would be much happier if we moved away from "@RichardLitt can take my sloppy writing and make it good", and towards "I think this is good. Do you agree, @RichardLitt?"

What you wrote is a good start. I would clean it up a bit and PR it to this repository.

[dignifiedquire]

I'm sorry @RichardLitt it wasn't meant that way. The issue is that I currently don't have time to work on aegir unless something is on fire. But you and @diasdavid were asking for this, so I did a simple brain dump in between and asked for you to take it further. If you want me to clean it up it will probably take a couple of weeks until I get to it.

[RichardLitt]

That's OK! this is a good start. There is no fire here. A couple of weeks or more is fine - now it is somewhere. \o/