proposal: `avoid_library_directive`

[kevmoo]

avoid_library_directive

Description

The library directive at the top of...libraries...is generally superfluous – UNLESS it's used to "anchor" a doc comment or an annotation (see https://github.com/dart-lang/linter/issues/3687).

The use of the "naked" library directives should be avoided.

Details

Not much more than the description.

Kind

Style

Good Examples

// Notice no library directive – not needed!

void main() {}

// Doc comments and/or annotations are a good reason to still use the library directive

/// This is a cool test library
@TestOn('vm')
library; // assuming https://github.com/dart-lang/language/issues/1073 lands with support for no-name library directives

void main() {...}

Bad Examples

// The library directive accomplishes NOTHING!

library pointless.library.here;

void main() {}

Discussion

See https://github.com/dart-lang/language/issues/1073 for the no-name library directive proposal.

Would "conflict" with the following lints. No point in enforcing conventions for names when we want to avoid library directives!

• https://dart-lang.github.io/linter/lints/package_prefixed_library_names.html
• https://dart-lang.github.io/linter/lints/library_names.html

This could likely be added to Effective Dart, I think.

Discussion checklist

• [x] List any existing rules this proposal modifies, complements, overlaps or conflicts with.
• [x] List any relevant issues (reported here, the SDK Tracker, or elsewhere).
• [x] If there's any prior art (e.g., in other linters), please add references here.
• [x] If this proposal corresponds to Effective Dart or Flutter Style Guide advice, please call it out. (If there isn’t any corresponding advice, should there be?)
• [x] If this proposal is motivated by real-world examples, please provide as many details as you can. Demonstrating potential impact is especially valuable.

[bwilkerson]

The lint should not flag library directives if the library has parts that use the library name in the part of directive (but the use of a URI in the part of directive shouldn't prevent the lint from firing).

[kevmoo]

The lint should not flag library directives if the library has parts that use the library name in the part of directive (but the use of a URI in the part of directive shouldn't prevent the lint from firing).

Although folks should NOT be using parts with library names anymore, too – right?

RE https://dart-lang.github.io/linter/lints/use_string_in_part_of_directives.html

[lrhn]

A library directive is needed if:

• It has metadata
• It has doc-comments
• it has a name, and a part which uses part of with that name. (If they don't use the use_string_in_part_of_directives lint, they can do that. If they use that lint, they'll probably stop having such a part of and this item stops applying.)
• it has a name and someone uses dart:mirrors.

The last point is undecidable, so basically a library declaration with a name cannot be considered guaranteed unnecessary.

I'd still be fine with linting the declaration if the only use is (potentially) using dart:mirrors. Then you can add the // ignore and a comment saying why. Using dart:mirrors to look up a library by name is obscure enough that it needs commentary.

Separately, the library name itself can be unnecessary. A @foo library foo.bar.baz; can still remove the name, even if the library declaration is not unnecessary. Is that a separate lint already, one we'd want, or could it be part of this one ("all unnecessary things about library declarations")?

[kevmoo]

FYI: the associated language feature has LANDED for Dart 1.19!

[kevmoo]

I've made a stab at implementing this – feedback welcome! https://github.com/dart-lang/linter/pull/3791

[pq]

Implemented w/ #3791 🎉