Site-www: Recommendations for /lib/src vs. /lib

[kwalrath]

Following up on #148, both https://www.dartlang.org/tools/pub/package-layout and https://www.dartlang.org/guides/libraries/create-library-packages have the following note (which, if still legit, should perhaps be an include instead of copied):

Tip for web apps: For the best performance when developing with dartdevc, put implementation files under /lib/src, instead of elsewhere under /lib. Also, avoid imports of package:package_name/src/....

@natebosch or @jakemac53 or @munificent, is favoring lib/src over lib something we want to recommend? If so, is it still a performance thing or just a best practice? Should the scope of this recommendation remain limited to dartdevc, or is it larger? If the latter, should it also be in Effective Dart?

[jakemac53]

This is a more general guideline from an organizational perspective (having a clear and explicit public vs internal api) and it is absolutely still valid from a performance perspective with build_runner and ddc/kernel/summaries. Our default module heuristics are designed to work with packages structured in this way.

[kwalrath]

Does Flutter code also have this preference for putting implementation files under /lib/src? If so, it seems like something we might want in Effective Dart.

/cc @filiph @RedBrogdon

[RedBrogdon]

I have never used /src outside of package development. All my apps use /lib for main.dart and a few other things, and then subdirectories inside /lib like "screens," "blocs," "widgets," and so on.

I always figured /src was for hiding away internal dart files in a package (like it's the directory equivalent of a leading underscore), which isn't really an issue when building an app.

[natebosch]

If we are able to bring an incremental kernel compilation pipeline over to flutter there _will_ be benefit to using src in that it will allow the module discover to create bigger modules for those files (each library _not_ under src is always it's own module when possible). Not sure how drastic that benefit would be in practice. This definitely does matter much more for published and shared dependencies than it does for root level application packages.

[munificent]

"Effective Dart" does already have "DON’T import libraries that are inside the src directory of another package.", so I think that's sufficient.