Rule category proposals

[srawlins]

With the ability to tag a lint rule with multiple categories, I'm exploring how we can take advantage, and what new categories we can introduce, to help people quickly categorize various rules in their head. In addition to "style," "errors," and "pub":

• maintainability / readability
  • annotate_overrides
  • annotate_redeclares
  • avoid_annotating_with_dynamic
  • avoid_bool_literals_in_conditional_expressions
  • avoid_classes_with_only_static_members
  • avoid_empty_else
  • avoid_positional_boolean_parameters
  • avoid_print
  • avoid_void_async
  • cast_nullable_to_non_nullable
• code bloat
  • avoid_unused_constructor_parameters
• binary size
  • avoid_annotating_with_dynamic
  • avoid_dynamic_calls
• code quality / best practices (as in, not style-related best practices, but best practices w.r.t. code quality, error-prone code, ...)
  • avoid_catches_without_on_clauses
  • avoid_catching_errors
  • avoid_null_checks_in_equality_operators
  • avoid_returning_this
  • avoid_shadowing_type_parameters
• flutter
  • avoid_unnecessary_containers
  • avoid_web_libraries_in_flutter
• runtime performance
  • avoid_slow_async_io
• correctness (maybe the same as "errors," but I'm tracking here to see if there are differences)
  • avoid_equals_and_hash_code_on_mutable_classes
  • avoid_implementing_value_types
• documentation
• avoid_renaming_method_parameters
• memory
  • avoid_field_initializers_in_const_classes
  • cancel_subscriptions
  • close_sinks
• web
  • avoid_double_and_int_checks
  • avoid_js_rounded_ints
  • avoid_web_libraries_in_flutter

[bwilkerson]

@MaryaBelanger @parlough

These should be coordinated with, and the basis for, the site-www effort to make it easier for users to find the lint rules they need. Your input on the right set of categories would be appreciated.

[MaryaBelanger]

This is great! FYI @srawlins, Parker and I are working on a mechanism to filter the full list of lints on the linter rules page based on better defining these categories.

A couple questions we discussed recently:

• Do we need to keep "Errors" as a category? Technically none of the lints are errors, but seem to be categorized by the fact that they help prevent errors by preventing bad code practices. We were thinking about recategorizing "Errors" to more granular, meaningful categories like "Bug prevention" (possibly the main catch all), but also probably other categories that better fit what kind of "error" the lint catches (like "memory optimization", "performance", "security", etc)
• I was thinking about a category for people writing code... professionally? I'm not sure how to word it though, I was thinking "Production code", "Large codebase", or even "Collaborative projects" (probably overlap with "consistency", "readability", "security", etc.). Does that make sound useful/make sense?

[srawlins]

Do we need to keep "Errors" as a category?

Great question! I want to look at this a little more closely, but I suspect we might have more specific categories like "brittle" or "rarely the thing you want" or "dangerous." But I bet we will still end up wanting / needing a more general "error-prone" category.

I was thinking about a category for people writing code... professionally?

Great idea. Concerns about code that is shared with other devs, and maintained long-term is definitely a category we could look at. I can keep this idea in mind when categorizing more (I only did A through C above 🤣 ).

[MaryaBelanger]

Btw, Parker and I are operating under the assumption that each lint will probably fall into multiple categories. E.g. avoid_print definitely falls under "maintainability"/"readability", but also maybe "security"/"production code".

Does that make sense for you? I notice you didn't repeat any in your list above. I can also see that might introduce "label bloat" where there's too many labels that are too similar or something...If you're concerned let us know!

---

Re: "brittle" and "dangerous":

I'm not sure how feasible this is, but I've also been thinking it's probably best to name the categories based on the goal/outcome of the lint. Like, if someone's thinking "I want lints that help me ..." or "My project is ..., what lints are good for that?", I think the categories should be worded in a way that fills that blank (as opposed to describing the problem).

I'm sure it won't be possible for every category, and maybe as this project moves along it'll become obvious it's just not a good idea.. But for now how does that sound? So like, the active, positive version of "dangerous" might be "security", and "brittle" might be "robust" or "failure-proof" (though that's a big promise 😅 ).

Does that sound like it'd be useful for users, at least for now while we're brainstorming?

[oaahmad]

Parker and I are working on a mechanism to filter the full list of lints

I'm starting a Dart side project, and was just struggling with the documentation for lints. I always like to start with include: package:flutter_lints/flutter.yaml and add a bunch of lints from there. The page that lists all the lints is very long and it would be nice to:

• Exclude lints in flutter_lints/flutter.yaml
• Exclude lints that were removed (from newer versions of Dart)
• Exclude lints that can conflict with the formatter
  • This is probably a separate issue (maybe there shouldn't be lints related to whitespace formatting)
• Exclude experimental lints
• Exclude lints that weren't released in a stable release yet

So in other words, I think any filters on that page would be more helpful if they acted like a multi-select (so I can exclude things) rather than having to pick a single category.

Just something to consider if you're working on filters.

[srawlins]

OK I've sent out https://dart-review.googlesource.com/c/sdk/+/371921 for review. @MaryaBelanger @parlough is there any infra that needs to be added to the pub.dev side before I can land this? No rush, I just don't want to land it if that causes a rush for something on your side.

I looked through all of the currently-marked "errors" rules and recategorized. Most rules still only have one category, but maybe they'd fall into more categories if we went more fine-grained.

Many rules do keep the sort of vague, "error-prone" label. I added "unintentional" to kind of mean, "uh, you just shouldn't do this" or "this doesn't do what you think it does" or "I don't think you meant to write this."

But "error-prone" remains, for example the rules, control_flow_in_finally, discarded_futures, do_not_use_environment, empty_statements, and a dozen more. These are generally not guaranteed runtime errors or likely whoopsies. Like if you typed bool.fromEnvironment, you definitely didn't accidentally type that (as opposed to accidentally leaving the type off a variable). So the lint rule is there to say, "whoa whoa, it looks like you thought this API was going to be useful, but let me steer you clear."

Anyways, the PR is open to lots of feedback, thanks!

[MaryaBelanger]

The categories in the CL lgtm! We'll use those when we start writing the new content. Will it be possible/not-too-much-work to change or adjust categories once we start using them?

I can't speak to the pub.dev side of things, you might want to ask the pub team.

[srawlins]

Thanks @MaryaBelanger! Which rules get categorized into which categories I think can be completely fluid. I don't think we'd be doing ourselves any favors by making it difficult to update/add/remove the categories of a rule.

I think that the categories themselves can be pretty fluid, unless the names are embedded in URLs. :/ Like if we have a page for all of the 'binary size' rules, then we'd need to build additional infra to rename things. This maybe wouldn't be difficult, and maybe it's inevitable, haha. I think no more complicated than the situation we have today for error codes and lint rules that can't be deleted.