Clarify when to use Part directives

[felangel]

Can you please clarify what is meant by:

Note: You may have heard of the part directive, which allows you to split a library into multiple Dart files. We recommend that you avoid using part and create mini libraries instead.

https://dart.dev/guides/libraries/create-library-packages#organizing-a-library-package

It’s a bit unclear if part usage is discouraged in general or just in the context of library creation and if so it would be nice to elaborate on the rationale. Happy to open a PR to improve the docs once this has been clarified. Thanks!

[kwalrath]

My understanding is that part was an early language feature that fell out of common use, except in automatically generated code. Also, the relatively new extension feature can be used in some places where part used to be necessary.

Does that sound right, @kevmoo or @munificent? How can we clarify our guidance?

[kevmoo]

I don't think there is a lot of overlap between extension members and parts. My suggested guidance: parts are useful for code generation or cases here libraries have to be big and should be broken into files. ...but it's pretty rare when a library has to be big. There are many ways to split things up...

…

On Mon, Apr 27, 2020 at 8:58 AM Kathy Walrath ***@***.***> wrote: My understanding is that part was an early language feature that fell out of common use, except in automatically generated code. Also, the relatively new extension feature can be used in some places where part used to be necessary. Does that sound right, @kevmoo <https://github.com/kevmoo> or @munificent <https://github.com/munificent>? How can we clarify our guidance? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2371 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAEFCX2OLYEF3WCEOK7J6LROWTS7ANCNFSM4MQ254ZQ> .

[munificent]

I agree with Kevin. Maybe say:

Note: You may have heard of the part directive, which allows you to split a library into multiple Dart files. Part files are useful for incorporating generated code into a library, but we otherwise recommend that you don't use them.

[felangel]

Thanks @kwalrath, @kevmoo, and @munificent for the clarification! Is there some justification for avoiding parts outside of code generation? I feel there are cases where parts are still very useful. Take the following scenario for example:

class Foo {...}

class Bar {...}

class MyClass extends Base<Foo, Bar>{...}

We can define Foo and Bar alongside MyClass which is fine but might lead to a somewhat bloated file.

Alternatively, we can define Foo and Bar separately and import them into my_class.dart but we then either need to re-export them, introduce a "barrel file", or use multiple imports to access Foo, Bar, and MyClass from elsewhere in the code.

I find parts are useful for this sort of scenario because they allow me to separate the implementations of these individual components while still representing them as parts of the whole MyClass.

part 'foo.dart';
part 'bar.dart';

class MyClass extends Base<Foo, Bar> {...}

I can then access Foo, Bar, and MyClass via a single import and it also helps when code generation is applied to Foo, Bar, or MyClass because a single .g.dart file is generated as opposed to 3.

Is there anything "wrong" with this approach? Thanks 🙏

[jorgecoca]

The case that @felangel described is what is being used in the flutter_bloc IDE extensions, and I personally like it a lot, since it makes the integration so much easier, and we do not need a barrel file just for the bloc (+ events and states).

[munificent]

The main problems is that those part files:

• Share the same private scope as the library and all other parts.
• Can't contain their own imports.

So you don't get the benefits of being able to reason about each file independently. They are deeply intertwined. It only really lets you break your file into smaller files textually but not conceptually. In fact, it can end up more confusing because the separate files lead you to think things are more encapsulated than they actually are.

Because of that, our experience is that for most users parts don't carry their weight as a feature.

[atsansone]

@munificent : Is this still a going concern?

[munificent]

I think this comment is still decent guidance. We don't really want users hand authoring part files. They're much better off using separate libraries and using export to compose them. But part files are widely used for generated code.

[minseok-jeong-gn]

For 2024 my use,
Just use part for code generation others none.