bwilkerson
commented
4 years ago Yes, the docs for lints need to be updated. They haven't been maintained as the language and SDK have evolved. And the performance-related lints are especially prone to getting out of date because of changes to the execution technologies (and might apply in some cases but not others).
While I think it would be great to link to authoritative sources, there might not be any source for some things, even when they're true at the time of writing. I'd also want to have a build step that detects broken links.
In addition to the issues you raised above I'd like to see them conform to the style of documentation we've adopted for the rest of the diagnostics.
pq
davidmorgan
jamesderlin
lukepighetti
It turns out that lint docs are a great way to settle an argument. On numerous occasions I've seen people linking to lint docs as if they are absolute truth; and I've done it myself.
Unfortunately, some lint docs are not correct, e.g.:
https://dart-lang.github.io/linter/lints/use_string_buffers.html claims performance difference; but when compiled to js, there isn't one \ https://dart-lang.github.io/linter/lints/prefer_final_locals.html makes the vague claim "allows the compiler to do optimizations"; was this ever true? Is it still true? \ https://dart-lang.github.io/linter/lints/avoid_slow_async_io.html makes performance claims that depend on the filesystem \ https://dart-lang.github.io/linter/lints/avoid_as.html makes a claim about removing the type check that is implementation dependent and almost certainly changed with Dart 2
I wonder if we could improve this. For example, we could require linking to an authoritative source for any claims that go beyond purely mechanical details of the lint.
For performance claims, I'd very much like to see links to benchmarks--and, more than that, to benchmarks that we actually run, so we notice when the claims in the lint are no longer true.
Thoughts? :)
Thanks!