Each lint should have a justification

[srawlins]

A lot of our rules' descriptions are too brief, so that the intention, or justification, is unclear. Examples:

http://dart-lang.github.io/linter/lints/avoid_returning_null_for_future.html - why would this be an error? http://dart-lang.github.io/linter/lints/avoid_slow_async_io.html - why are these slower? how much slower? Is there a bug for this? http://dart-lang.github.io/linter/lints/no_adjacent_strings_in_list.html - do what instead? http://dart-lang.github.io/linter/lints/avoid_as.html - no explanation

Having clear justifications will allow users to choose whether to enable a lint or not.

[pq]

If we wanted to support this formally, I'd be up for growing the LintRule API. For example, what if a rule where defined something like this:

class MyRule extends LintRule implements NodeLintRule {
  MyRule()
      : super(
            name: 'my_rule',
            description: _desc,
            details: _details,
            motivation: ...  // <=💡motivational details go here
            group: Group.style);

I'm not wedded to the details at all FWIW, just curious how people feel about supporting this with an API (optional or required) vs. doc conventions.

cc @InMatrix who might have thoughts too.

[bwilkerson]

Often times the description, motivation and examples need to be interleaved in order to improve the readability of the text. I don't think that either a documentation convention ("put motivation here") or separate API provide the flexibility we need.

[pq]

Interestingly, the issues cited by @bwilkerson echo possible concerns with the ErrorBuilder API we're looking at for flutter foundation.

📟 @jacob314 FYI