Update Effective Dart Design Guidelines to Reflect Dart 3.0 Class Modifiers #6449

MiniPiku · 2025-02-22T01:05:06Z

This PR updates the Effective Dart Design Guidelines to align with Dart 3.0's introduction of class modifiers. The changes include:

For API Maintainers:

Removed the recommendation to document whether a class supports being extended or used as an interface.

Added guidance to use class modifiers (e.g., final, sealed, interface, mixin) to explicitly define a class's capabilities.

Emphasized that class modifiers should replace manual documentation for enforcing restrictions on extending or implementing classes.

For Users:

Removed guidelines advising users to avoid extending or implementing classes not meant for it, as these restrictions are now enforced by class modifiers in Dart 3.0.

This change ensures the guidelines are up-to-date with Dart's latest features and best practices.

Fixes: #6437

1. Renamed the variable json to data throughout the section. 2. Updated the text to clarify that the example works with deserialized data (e.g., parsed from JSON) rather than raw JSON strings. 3. Ensured consistency in variable naming and explanations. This update makes the documentation more accurate and avoids misleading readers into thinking that the variable holds a JSON string. If you’re contributing to the Dart documentation, you can submit this change as a pull request to the [site-www repository](https://github.com/dart-lang/site-www)

Update the 'Classes and mixins' section to reflect Dart 3.0’s class modifier features: - Revise API maintainer guidelines to recommend inal, �ase, etc., over documentation for controlling class extension and implementation. - Remove obsolete user guidelines ('AVOID extending/implementing') as compiler enforcement via modifiers replaces the need for these. - Add a note explaining the shift and obsoletion, placed at the section’s start for context. This aligns the guidelines with modern Dart language capabilities, reducing reliance on docs.

antfitch · 2025-02-26T22:58:40Z

/gcbrun

dart-github-bot · 2025-02-26T23:01:11Z

Visit the preview URL for this PR (updated for commit a57c770):

https://dart-dev--pr6449-guidelines-update-v1-mjkxucz1.web.app

antfitch

Looks great! A few notes added plus it looks like you need to decouple some JSON changes.

antfitch · 2025-02-26T23:20:35Z

src/content/effective-dart/design.md

-classes. But Dart does not require all code to be defined inside a
-class—you can define top-level variables, constants, and functions like
-you can in a procedural or functional language.
+**Note:** As of Dart 3.0, class modifiers (e.g., `final`, `base`, `interface`) 


We should only include very basic top-level information under this high-level heading. Let's revert this to what was already there, but I would advise adding one bullet with a sentence or two that lets people know that classes can be restricted.

I believe you've already captured these other details in subsections. If something is here but not in one of those sections, let's move the content to that section.

antfitch · 2025-02-26T23:22:35Z

src/content/effective-dart/design.md


-### DO document if your class supports being used as an interface
+### DO use class modifiers to control if your class can be used as an interface


Suggested change

### DO use class modifiers to control if your class can be used as an interface

### DO use class modifiers to control if your class can be an interface

I think we can cut a few words from this without removing meaning.

antfitch · 2025-02-26T23:24:39Z

src/content/effective-dart/design.md

-to implement, then changing those classes becomes very difficult. That
-difficulty in turn means the libraries you rely on are slower to grow and adapt
-to new needs.
+Since Dart 3.0, class modifiers like `final`, `base`, or `sealed` 


Suggested change

Since Dart 3.0, class modifiers like `final`, `base`, or `sealed`

Class modifiers like `final`, `base`, or `sealed`

Dart 3 has been out for a while. I think we can avoid mentioning it. @johnpryan, your thoughts?

I agree - we can leave this out here.

antfitch · 2025-02-26T23:26:04Z

src/content/effective-dart/design.md


-If your class can be used as an interface, mention that in the class's doc
-comment.
+With Dart 3.0’s class modifiers, you can restrict implementation using


Can you have this section mirror the last one as closely as possible? It's okay if they sound very similar. I like the wording you used in the previous section for extending.

antfitch · 2025-02-26T23:35:01Z

examples/language/lib/patterns/json.dart

I see several changes in here related to JSON data. I suspect these are not part of the class modifiers PR. Can you update your PR?

The json changes are of another PR
but this PR doesn't contain any of those changes
this one is created on a separate branch
idk why its showing like that :/

the conflict warning has been taken care of :)
a false indentation in 'src/content/language/patterns.md' has been creating the problem
thank you

1)Reverted back the top level information 2)Shortend the wordings as mentioned 3)Rephrased the lines 4)Mirrored the mentioned section as said

MiniPiku · 2025-02-27T05:05:08Z

@antfitch i made the mentioned changes as said
can you kindly take a look at the renewed PR
thank you :)

antfitch · 2025-02-27T17:34:45Z

src/content/effective-dart/design.md

 allow you to enforce whether a class can be extended directly in code. 
 For example, use `final class A {}` to prevent extension, 
 or `base class B {}` to allow extension only within the same library. 
 Rely on these modifiers rather than documentation to communicate and 
 enforce your intent.


-### DO use class modifiers to control if your class can be used as an interface
+### ### DO use class modifiers to control if your class can be an interface


Delete extra ###

antfitch · 2025-02-27T17:35:08Z

src/content/effective-dart/design.md

-`final`, `base`, or `interface`. For example, `final class A {}` 
-prevents implementation, while `interface class C {}` allows it explicitly. 
-Use these modifiers to enforce your design intent instead of relying solely 
+you can also restrict implementation using


You can restrict implementation using

antfitch · 2025-02-27T17:36:38Z

src/content/effective-dart/design.md

- For example, `final class A {}` prevents implementation, while `interface class C {}` allows it explicitly.
- Use these modifiers to enforce your design intent instead of relying solely on documentation.
-
+Classes. But Dart does not require all code to be defined inside a


Original text is still missing.

antfitch · 2025-02-27T17:39:00Z

examples/language/lib/patterns/json.dart~

This appears to be an artifact from another PR. Maybe the answer is to start a new PR with your changes for Effective Dart Design? Otherwise, keep working on getting this file (and patterns.md and patterns.md~) removed from the PR.

johnpryan · 2025-02-27T17:34:43Z

src/content/effective-dart/design.md

@@ -519,10 +519,9 @@ class in a single library.

 ## Classes and mixins

-Dart is a "pure" object-oriented language in that all objects are instances of
-classes. But Dart does not require all code to be defined inside a
+Classes. But Dart does not require all code to be defined inside a


The word "class" shouldn't be capitalized here.

Suggested change

Classes. But Dart does not require all code to be defined inside a

classes. But Dart does not require all code to be defined inside a

johnpryan · 2025-02-27T17:35:11Z

src/content/effective-dart/design.md

 class—you can define top-level variables, constants, and functions like
-you can in a procedural or functional language.
+you can in a procedural or functional language


Missing period:

Suggested change

you can in a procedural or functional language

you can in a procedural or functional language.

johnpryan · 2025-02-27T17:42:59Z

src/content/effective-dart/design.md

-class, state that. Suffix the class name with `Base`, or mention it in the
-class's doc comment.
+Class modifiers like `final`, `base`, or `sealed` 
+allow you to enforce whether a class can be extended directly in code. 


Suggested change

allow you to enforce whether a class can be extended directly in code.

enforce whether a class can be extended.

johnpryan · 2025-02-27T17:44:48Z

src/content/effective-dart/design.md

+Rely on these modifiers rather than documentation to communicate and 
+enforce your intent.


Suggested change

Rely on these modifiers rather than documentation to communicate and

enforce your intent.

Use these modifiers to communicate your intent, rather than relying on documentation.

johnpryan · 2025-02-27T17:47:50Z

src/content/effective-dart/design.md



-### AVOID implementing a class that isn't intended to be an interface
+### ### DO use class modifiers to control if your class can be an interface


Your proposed rule is from the perspective of someone writing the library, but the original version was intended for those who are using a library. This section is talking about classs that aren't intended to be an interface, and while it would be nice if all such classes were using class modifiers to enforce these rules (as recommended above), it's still possible that a developer could run into these problems so I would vote to keep this section as-is.

johnpryan · 2025-02-27T17:49:12Z

src/content/language/patterns.md~

@@ -0,0 +1,447 @@
+---
+title: Patterns


Did you intend to make a copy of this file with a ~ at the end? Could you double check that your changes to this file are showing up correctly in the diff?

1)Made neccesary changes as said 2)Delete 'src/content/language/patterns.md~' file 3)Undid unnecessary indentation in 'src/content/language/patterns.md' file

MiniPiku · 2025-02-27T18:38:52Z

@antfitch @johnpryan kindly take a look at the changes made
41f58b3
thank you

examples/language/lib/patterns/json.dart~

src/content/effective-dart/design.md

…e an interface'

MiniPiku · 2025-02-27T19:42:21Z

@johnpryan does this rephrasing works ?
or you can suggest any other changes if required

1)Reverted rule3 to rule 1 2)let the 2nd section as it is

johnpryan · 2025-02-27T20:14:20Z

This is looking good, could you take a look and double check that there aren't extra changes committed that are unrelated? I see some changes to .json files that don't seem to belong here.

MiniPiku · 2025-02-27T20:17:31Z

yeah i removed the json file that was unnecessarily getting committed to this PR i dont know why
i removed it from my side so you wont have to delete it manually from your side

eernstg

Commented on just one place that needs to say interface rather than base (base doesn't restrict extends, it restricts implements).

eernstg · 2025-03-01T07:31:40Z

src/content/effective-dart/design.md


+Class modifiers like `final`, `interface`, or `sealed`
+restrict how a class can be extended.
+For example, use `final class A {}` or `base class B {}` to prevent 


It can't be base class B {} because that does not prevent extension outside the current library. It's interface that prevents extends (but allows implements).

changed base class B {} to interface class B{}

MiniPiku · 2025-03-02T15:07:35Z

@eernstg just a follow-up comment that the said changes have been made
kindly take a look

eernstg

Thanks! It looks good to me now.

I haven't pressed the 'Approve' button because I'm from the language team and the final acceptance should be provided by the site-www team.

src/content/effective-dart/_toc.md

johnpryan · 2025-03-04T17:43:16Z

src/content/effective-dart/_toc.md

@@ -199,8 +199,7 @@ the project:

 * <a href='/effective-dart/design#avoid-defining-a-one-member-abstract-class-when-a-simple-function-will-do'>AVOID defining a one-member abstract class when a simple function will do.</a>
 * <a href='/effective-dart/design#avoid-defining-a-class-that-contains-only-static-members'>AVOID defining a class that contains only static members.</a>
-* <a href='/effective-dart/design#avoid-extending-a-class-that-isnt-intended-to-be-subclassed'>AVOID extending a class that isn't intended to be subclassed.</a>


This line shouldn't be removed AFAICT, can you make sure you re-ran the generator?

./dash_site effective-dart

yep my bad i thought that this section was removed from the design.md file that's why i remove the link too
lemme readd that
thanks for pointing it out

…e to the previously failing task even when the anchor link is correct

johnpryan · 2025-03-04T19:12:33Z

Can you revert 4dc729d, thanks!

…ctly, due to the previously failing task even when the anchor link is correct" This reverts commit 4dc729d.

MiniPiku · 2025-03-04T19:31:29Z

@johnpryan done
but before this this it was giving an Github PR run issue with the anchor link idk why

src/content/language/patterns.md

examples/language/lib/patterns/json.dart

johnpryan

LGTM

antfitch

Looks great!

antfitch · 2025-03-04T22:57:46Z

/gcbrun

antfitch · 2025-03-04T23:00:57Z

@MiniPiku it looks like a link is broken. Can you fix that? The link is in effective-dart.md and needs to point to: design#do-use-class-modifiers-to-control-if-your-class-can-be-an-interface

antfitch

One last change to fix a broken link. Looks great!

MiniPiku · 2025-03-05T16:07:09Z

@antfitch kindly take a look
i guess this should work

antfitch · 2025-03-05T16:53:58Z

/gcbrun

antfitch

Looks great!

MiniPiku added 4 commits February 16, 2025 01:24

fixed(Indentation): Restored proper spacing in code block

7a12801

Changes:

3a45342

MiniPiku mentioned this pull request Feb 22, 2025

Classes and mixins section of Design chapter of Effective Dart should be rewritten accounting class modifiers feature of Dart 3.0 #6437

Closed

1 task

antfitch self-requested a review February 26, 2025 22:54

antfitch requested a review from johnpryan February 26, 2025 23:08

antfitch reviewed Feb 26, 2025

View reviewed changes

antfitch mentioned this pull request Feb 26, 2025

Added guideline about class modifiers, removed obsolete ones #6438

Closed

4 tasks

Changes made :

e3db6c1

1)Reverted back the top level information 2)Shortend the wordings as mentioned 3)Rephrased the lines 4)Mirrored the mentioned section as said

MiniPiku force-pushed the guidelines-update-v1 branch from 902ea69 to e3db6c1 Compare February 27, 2025 05:03

Conflicts resolved in 'src/content/language/patterns.md'

bc82de9

antfitch reviewed Feb 27, 2025

View reviewed changes

johnpryan requested changes Feb 27, 2025

View reviewed changes

Changes made :

41f58b3

1)Made neccesary changes as said 2)Delete 'src/content/language/patterns.md~' file 3)Undid unnecessary indentation in 'src/content/language/patterns.md' file

MiniPiku force-pushed the guidelines-update-v1 branch from 4f8f2f7 to 41f58b3 Compare February 27, 2025 18:36

johnpryan reviewed Feb 27, 2025

View reviewed changes

examples/language/lib/patterns/json.dart~ Outdated Show resolved Hide resolved

johnpryan reviewed Feb 27, 2025

View reviewed changes

src/content/effective-dart/design.md Show resolved Hide resolved

rephrasing '### DO use class modifiers to control if your class can b…

5855642

…e an interface'

MiniPiku force-pushed the guidelines-update-v1 branch from 2e73fae to 5855642 Compare February 27, 2025 19:27

Changes made :

13650d3

1)Reverted rule3 to rule 1 2)let the 2nd section as it is

MiniPiku force-pushed the guidelines-update-v1 branch from cc5ad65 to 13650d3 Compare February 27, 2025 20:11

johnpryan approved these changes Feb 27, 2025

View reviewed changes

eernstg reviewed Mar 1, 2025

View reviewed changes

changed 'base class B {}' --> 'interface class B{}'

45f381f

MiniPiku force-pushed the guidelines-update-v1 branch from 6340eff to 45f381f Compare March 1, 2025 13:48

eernstg reviewed Mar 3, 2025

View reviewed changes

src/content/effective-dart/_toc.md Outdated Show resolved Hide resolved

antfitch assigned MiniPiku Mar 3, 2025

added missing period at the end

e586ada

MiniPiku force-pushed the guidelines-update-v1 branch from 4e99e3c to e586ada Compare March 3, 2025 20:13

johnpryan reviewed Mar 4, 2025

View reviewed changes

re-added the previously removed link in '_toc.md' file

75e7570

MiniPiku force-pushed the guidelines-update-v1 branch from 61a1b25 to 75e7570 Compare March 4, 2025 17:57

Added a post job step to ensure the emulator shuts down correctly, du…

4dc729d

…e to the previously failing task even when the anchor link is correct

Revert "Added a post job step to ensure the emulator shuts down corre…

9f57c4a

…ctly, due to the previously failing task even when the anchor link is correct" This reverts commit 4dc729d.

MiniPiku force-pushed the guidelines-update-v1 branch from b27935e to 9f57c4a Compare March 4, 2025 19:28

johnpryan requested changes Mar 4, 2025

View reviewed changes

src/content/language/patterns.md Outdated Show resolved Hide resolved

examples/language/lib/patterns/json.dart Outdated Show resolved Hide resolved

johnpryan approved these changes Mar 4, 2025

View reviewed changes

antfitch approved these changes Mar 4, 2025

View reviewed changes

antfitch requested changes Mar 4, 2025

View reviewed changes

antfitch added this to the Dart 3.8 milestone Mar 4, 2025

modified the link

eff55ab

MiniPiku force-pushed the guidelines-update-v1 branch from c0cbf6f to eff55ab Compare March 5, 2025 16:06

Merge branch 'main' into guidelines-update-v1

a57c770

antfitch approved these changes Mar 5, 2025

View reviewed changes

antfitch merged commit eb1ad75 into dart-lang:main Mar 5, 2025
10 checks passed


		### DO document if your class supports being used as an interface
		### DO use class modifiers to control if your class can be used as an interface

	Since Dart 3.0, class modifiers like `final`, `base`, or `sealed`
	Class modifiers like `final`, `base`, or `sealed`

	Classes. But Dart does not require all code to be defined inside a
	classes. But Dart does not require all code to be defined inside a

	you can in a procedural or functional language
	you can in a procedural or functional language.

	allow you to enforce whether a class can be extended directly in code.
	enforce whether a class can be extended.

		Rely on these modifiers rather than documentation to communicate and
		enforce your intent.

	Rely on these modifiers rather than documentation to communicate and
	enforce your intent.
	Use these modifiers to communicate your intent, rather than relying on documentation.



		### AVOID implementing a class that isn't intended to be an interface
		### ### DO use class modifiers to control if your class can be an interface

Update Effective Dart Design Guidelines to Reflect Dart 3.0 Class Modifiers #6449

Update Effective Dart Design Guidelines to Reflect Dart 3.0 Class Modifiers #6449

Conversation

MiniPiku commented Feb 22, 2025 • edited by antfitch Loading

antfitch commented Feb 26, 2025

dart-github-bot commented Feb 26, 2025 • edited Loading

antfitch left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

antfitch Feb 26, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MiniPiku commented Feb 27, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MiniPiku commented Feb 27, 2025

MiniPiku commented Feb 27, 2025

johnpryan commented Feb 27, 2025

MiniPiku commented Feb 27, 2025

eernstg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MiniPiku Mar 1, 2025 • edited Loading

Choose a reason for hiding this comment

MiniPiku commented Mar 2, 2025

eernstg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnpryan commented Mar 4, 2025

MiniPiku commented Mar 4, 2025

johnpryan left a comment

Choose a reason for hiding this comment

antfitch left a comment

Choose a reason for hiding this comment

antfitch commented Mar 4, 2025

antfitch commented Mar 4, 2025 • edited Loading

antfitch left a comment

Choose a reason for hiding this comment

MiniPiku commented Mar 5, 2025

antfitch commented Mar 5, 2025

antfitch left a comment

Choose a reason for hiding this comment

MiniPiku commented Feb 22, 2025 •

edited by antfitch

Loading

dart-github-bot commented Feb 26, 2025 •

edited

Loading

antfitch Feb 26, 2025 •

edited

Loading

MiniPiku Mar 1, 2025 •

edited

Loading

antfitch commented Mar 4, 2025 •

edited

Loading