[rule links] reduce visual clutter proposal

[hshoff]

My quest for less clutter continues (#695)

meteor/javascript has a clever solution for rule linking, they inline the eslint logo and link to the rule.

I propose we adopt a similar style but with links at the end.

Current

• 2.1 Use const for all of your references; avoid using var. eslint: prefer-const, no-const-assign

  Why? This ensures that you can't reassign your references, which can lead to bugs and difficult to comprehend code.

  // bad
  var a = 1;
  var b = 2;
  
  // good
  const a = 1;
  const b = 2;

• 2.2 If you must reassign references, use let instead of var. eslint: no-var jscs: disallowVar

  Why? let is block-scoped rather than function-scoped like var.

Proposal

• 2.1 Use const for all of your references; avoid using var.

  Why? This ensures that you can't reassign your references, which can lead to bugs and difficult to comprehend code.

  // bad
  var a = 1;
  var b = 2;
  
  // good
  const a = 1;
  const b = 2;

• 2.2 If you must reassign references, use let instead of var.

  Why? let is block-scoped rather than function-scoped like var.

[gergoerdosi]

This has the disadvantage of searching. Sometimes when linting shows an error, I copy the ESLint rule from the command line and search for it in the style guide to find the relevant part. This won't be possible with icons.

[hshoff]

@gergoerdosi excellent point, hadn't considered that use case

[hshoff]

How about this instead?

• 2.1 Use const for all of your references; avoid using var. prefer-const, no-const-assign
• 2.2 If you must reassign references, use let instead of var. no-var disallowVar

[ljharb]

Personally I don't find it visually cluttering to have the rules present, nor the word "eslint" or "jscs" - and in fact i might be grepping through all "eslint" instances in the doc if I wanted to review things.