Update Effective Dart Design Guidelines to Reflect Dart 3.0 Class Modifiers

examples/language/lib/patterns/json.dart

@@ -2,18 +2,18 @@
 
 void main() {
   // #docregion json-1
-  var json = {
+  var data = {
     'user': ['Lily', 13],
   };
-  var {'user': [name, age]} = json;
+  var {'user': [name, age]} = data;
   // #enddocregion json-1
 
   {
     // #docregion json-2
-    if (json is Map<String, Object?> &&
-        json.length == 1 &&
-        json.containsKey('user')) {
-      var user = json['user'];
+    if (data is Map<String, Object?> &&
+        data.length == 1 &&
+        data.containsKey('user')) {
+      var user = data['user'];
       if (user is List<Object> &&
           user.length == 2 &&
           user[0] is String &&
@@ -27,7 +27,7 @@ void main() {
   }
   {
     // #docregion json-3
-    if (json case {'user': [String name, int age]}) {
+    if (data case {'user': [String name, int age]}) {
       print('User $name is $age years old.');
     }
     // #enddocregion json-3

src/content/effective-dart/_toc.md

@@ -200,7 +200,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>
-* <a href='/effective-dart/design#do-document-if-your-class-supports-being-extended'>DO document if your class supports being extended.</a>
+* <a href='/effective-dart/design#do-use-class-modifiers-to-control-if-your-class-can-be-extended'>DO use class modifiers to control if your class can be extended.</a>
 * <a href='/effective-dart/design#avoid-implementing-a-class-that-isnt-intended-to-be-an-interface'>AVOID implementing a class that isn't intended to be an interface.</a>
 * <a href='/effective-dart/design#do-document-if-your-class-supports-being-used-as-an-interface'>DO document if your class supports being used as an interface.</a>
 * <a href='/effective-dart/design#prefer-defining-a-pure-mixin-or-pure-class-to-a-mixin-class'>PREFER defining a pure <code>mixin</code> or pure <code>class</code> to a <code>mixin class</code>.</a>

src/content/effective-dart/design.md

@@ -621,12 +621,13 @@ doesn't do that, it's best to assume you should *not* extend the class.
 Otherwise, later changes to it may break your code.
 
 
-### DO document if your class supports being extended
-
-This is the corollary to the above rule. If you want to allow subclasses of your
-class, state that. Suffix the class name with `Base`, or mention it in the
-class's doc comment.
+### DO use class modifiers to control if your class can be extended
 
+Class modifiers like `final`, `interface`, or `sealed`
+restrict how a class can be extended.
+For example, use `final class A {}` or `interface class B {}` to prevent 
+extension outside the current library.
+Use these modifiers to communicate your intent, rather than relying on documentation.
 
 ### AVOID implementing a class that isn't intended to be an interface
 
@@ -652,11 +653,14 @@ implicit interfaces except for classes that are clearly intended to be
 implemented. Otherwise, you may introduce a coupling that the author doesn't
 intend, and they may break your code without realizing it.
 
-### DO document if your class supports being used as an interface
-
-If your class can be used as an interface, mention that in the class's doc
-comment.
+### DO use class modifiers to control if your class can be an interface
 
+When designing a library, use class modifiers like `final`, `base`, or `sealed` to enforce intended
+usage. For example, use `final class C {}` or `base class D{}` to prevent
+implementation outside the current library.
+While it's ideal for all libraries to use these modifiers to enforce design intent,
+developers may still encounter cases where they aren't applied. In such cases, be mindful of
+unintended implementation issues.
 
 <a id="do-use-mixin-to-define-a-mixin-type"></a>
 <a id="avoid-mixing-in-a-class-that-isnt-intended-to-be-a-mixin"></a>

src/content/language/patterns.md

@@ -360,14 +360,14 @@ double calculateArea(Shape shape) => switch (shape) {
 ### Validating incoming JSON
 
 [Map][] and [list][] patterns work well for destructuring key-value pairs in
-JSON data:
+deserialized data, such as data parsed from JSON:
 
 <?code-excerpt "language/lib/patterns/json.dart (json-1)"?>
 ```dart 
-var json = {
+var data = {
   'user': ['Lily', 13],
 };
-var {'user': [name, age]} = json;
+var {'user': [name, age]} = data;
 ```
 
 If you know that the JSON data has the structure you expect,
@@ -379,10 +379,10 @@ Without patterns, validation is verbose:
 
 <?code-excerpt "language/lib/patterns/json.dart (json-2)"?>
 ```dart
-if (json is Map<String, Object?> &&
-    json.length == 1 &&
-    json.containsKey('user')) {
-  var user = json['user'];
+if (data is Map<String, Object?> &&
+    data.length == 1 &&
+    data.containsKey('user')) {
+  var user = data['user'];
   if (user is List<Object> &&
       user.length == 2 &&
       user[0] is String &&
@@ -402,7 +402,7 @@ method of validating JSON:
 
 <?code-excerpt "language/lib/patterns/json.dart (json-3)"?>
 ```dart
-if (json case {'user': [String name, int age]}) {
+if (data case {'user': [String name, int age]}) {
   print('User $name is $age years old.');
 }
 ```