No more "strong mode" #694

kwalrath · 2018-03-21T20:28:19Z

Changes to the Dart 2 site to move away from strong mode, which no longer makes sense in Dart 2.

Staged at URLs like:
https://kw-www-dartlang-1.firebaseapp.com/guides/language/sound-dart
https://kw-www-dartlang-1.firebaseapp.com/guides/language/sound-problems
https://kw-www-dartlang-1.firebaseapp.com/dart-2 (interim change; more to come in another PR)
https://kw-www-dartlang-1.firebaseapp.com/guides/language/analysis-options

@bwilkerson Could you please review my changes to Customize Static Analysis? I made a lot of guesses.

/cc @anders-sandholm @mit-mit @mjohnsullivan

Contributes to #602
Fixes #676

Interim save

chalin

Overall, looking quite good! My main quibbles are about the rather loose use of "sound" instead of "type safe" (please see inlined comments). Maybe I'm being too pedantic. @eernstg could you chime in?

chalin · 2018-03-21T22:32:38Z

src/_guides/language/analysis-options.md

-
-The simplest way to enable strong mode is to specify
-`strong-mode: true` in the analysis-options file:
+To find places in your code that could use explicit types,


Instead of

To find places in your code that could use explicit types,

how about either

To find places in your code that lack explicit type annotations,

or simply

To find places in your code that are implicitly typed,

I didn't want to imply that you should explicitly type everything. It's fine to lack explicit type annotations, as long as the inferred type isn't (unintentionally) dynamic, right?

In that case, implicit-casts isn't relevant here. Those are perfectly fine and won't infer dynamic.

So, what is the purpose of this section, now that it's no longer telling you how to enable strong mode?

The section promotes the part of the original that tells you how to enable more checks, to be a full section, but without the initial part, that feels out-of-place.

So, maybe a lead-in like:

You can enable more static checks on top of the Dart 2 type system,
to tell you where the type system would allow a down-cast by inserting a run-time check,
or where the type inference cannot find a useful type and defaults to inferring dynamic.

Yes, that is totally fine, and will be the preference of some developers

I would phrase this along the lines of "You can enable additional flags to do more checks statically. To statically find places in your code where a downcast might result in a runtime error, set implicit-casts to false; and to make inference report errors in places where it is unable to infer a type other than dynamic, set implicit-dynamic to false".

chalin · 2018-03-21T22:35:49Z

src/_guides/language/analysis-options.md

@@ -146,43 +133,27 @@ String s = o;  // Implicit downcast
 String s2 = s.substring(1);
 {% endprettify %}

-  This flag defaults to `true`.
-
 `implicit-dynamic: <bool>`
 : A value of `false` ensures that the type inference engine never chooses


"never chooses dynamic" tells us what it doesn't do. We haven't yet in this subsection said what happens when these flags are set to false. We should state that an issue is reported (I'm not sure what the default issue is, but in any case I think that it can be changed via configuration ... or maybe that is only for the linter rules).

Yeah, I noticed it was vague, but I wasn't trying to fix existing issues.

chalin · 2018-03-21T22:36:32Z

src/_guides/language/analysis-options.md

@@ -146,43 +133,27 @@ String s = o;  // Implicit downcast
 String s2 = s.substring(1);


How about embedding the actually analyzer issue that is reported? (Similar to what is done elsewhere in the docs. I can help with this if you'd like.)

I should learn how to do this. Maybe you could walk me through it tomorrow or Friday sometime?

Certainly. Here is an example: https://github.com/dart-lang/site-www/pull/694/files#r176273967

chalin · 2018-03-21T22:39:09Z

src/_guides/language/index.md

-    How and why to write sound Dart code, and how to use strong mode to
-    enable soundness.
+<li markdown="1"> [Dart's Type System](/guides/language/sound-dart)<br>
+    Learn about Dart's sound static type system.


Drop "static" (since soundness only makes sense in the context of a static type system).

chalin · 2018-03-21T22:41:23Z

src/_guides/language/sound-dart.md

@@ -1,54 +1,51 @@
 ---
-title: Strong Mode Dart
+title: Dart's Type System


How about "Type Safe Dart"?

I think we wanted to move toward this being a page about the type system, in general. Otherwise, I might've gone back to its first name, "Sound Dart".

Opinions, @anders-sandholm / @mit-mit / @mjohnsullivan?

I really like the title 'Dart's Type System' and I think it's a nice general title for a page that covers an overall overview of how the typing system works.

chalin · 2018-03-21T23:15:26Z

src/_guides/language/sound-dart.md

@@ -183,35 +145,26 @@ A sound type system has several benefits:
  code is much less efficient.


In the previous sentence:

While AOT compilation is possible without ~~strong~~ types, the generated
code is much less efficient.

chalin · 2018-03-21T23:16:25Z

src/_guides/language/sound-dart.md

-Dart's strong mode implementation, which enables soundness, consists
-of three pieces:
+  For web apps, sound typing allows
+  [dartdevc][] to generate cleaner, more compact JavaScript.


Should we combine "Better AOT" with "Cleaner JS" (essentially the latter is a special case of the former).

I think I'll just delete the "cleaner JS" unless someone objects.

chalin · 2018-03-21T23:24:21Z

src/_guides/language/sound-dart.md


 ### Example 1: From Map\<String, dynamic> to `var`

-Original definition:
+Explicit definition:


How about:

Explicitly type-annotated declaration:

or

Explicitly typed declaration:

Or "Explicitly typed variable declaration". I think it's important to say that it's the type of the variable that's important here.

chalin · 2018-03-21T23:25:11Z

src/_guides/language/sound-dart.md


 <?code-excerpt "strong/lib/strong_analysis.dart (type-inference-1-orig)"?>
 {% prettify dart %}
 Map<String, dynamic> arguments = {'argA': 'hello', 'argB': 42};
 {% endprettify %}

-New definition:
+Definition with var:


How about:

Implicitly typed definition using var:

Implicitly typed variable declaration, using var:

chalin · 2018-03-21T23:30:24Z

src/_guides/language/sound-dart.md

+**[PENDING: That's unclear. Why isn't it `List<String>`?
+  `foo` used to be `methodCall`, if that helps.]**
+{% endcomment %}
+


Maybe we can just drop this example because it is confusing more than anything else.

Why isn't it List<String>?

All we know is the foo yields a value whose type can respond to operator [] methods and that the type of the argument to [] is String.

I think it's confusing to use foo before it's introduced. Even in the previous example.
I can't see what the example is trying to say, so either figure that out, or remove it entirely.

chalin · 2018-03-21T23:46:25Z

src/_guides/language/sound-problems.md


 {:.fails-sa}
 <?code-excerpt "strong/lib/common_problems_analysis.dart (is-strong-mode-enabled)"?>
 {% prettify dart %}
 bool b = [0][0];
 {% endprettify %}

-If you're using strong mode, you'll see the following issue from the analyzer:
+With type-safe Dart, the analyzer produces the following error:

 {:.console-output}
 <?code-excerpt "strong/analyzer-2-results.txt" retain="/'int' can't be .* 'bool'.*common_problems/"?>
 ```nocode
 error • A value of type 'int' can't be assigned to a variable of type 'bool' • invalid_assignment
 ```


Here is an example of embedding an analyzer error.

kwalrath · 2018-03-21T23:52:59Z

I'm leery of changing the "sound" wording because @Sfshaza spent a lot of time getting the terminology right. On the other hand, the more consistent and correct and clear we are, the better.

kwalrath · 2018-03-21T23:55:00Z

Adding people who reviewed the original page: @filiph @lrhn @leafpetersen

mit-mit · 2018-03-22T08:06:46Z

I think overall this is a great improvement, thanks @kwalrath !

lrhn · 2018-03-22T07:23:16Z

src/_guides/language/analysis-options.md

-
-The simplest way to enable strong mode is to specify
-`strong-mode: true` in the analysis-options file:
+To find places in your code that could use explicit types,


In that case, implicit-casts isn't relevant here. Those are perfectly fine and won't infer dynamic.

So, what is the purpose of this section, now that it's no longer telling you how to enable strong mode?

The section promotes the part of the original that tells you how to enable more checks, to be a full section, but without the initial part, that feels out-of-place.

So, maybe a lead-in like:

You can enable more static checks on top of the Dart 2 type system,
to tell you where the type system would allow a down-cast by inserting a run-time check,
or where the type inference cannot find a useful type and defaults to inferring dynamic.

lrhn · 2018-03-22T07:27:55Z

src/_guides/language/analysis-options.md

+{% endcomment %}
+
+You can use the flags together or separately.
+Both default to `true`.


Maybe:

Both default to true, which provides just the plain Dart 2 behavior with no extra warnings.

I want to emphasize that these flags provide warnings above and beyond what the language specifies, and it's perfectly reasonable to have programs with such warnings.

I'm not really sure why we want to emphasize this?

Good point. This document as all about flags to the analyzer, I think I was reading this as being in the context of describing strong mode.

On the other hand, I do find it extremely confusing that the flags default to true, and that you turn the extra analyzer feature on by making them false. I think that deserves some explanation, so I'd still like to say that true means language-as-specified, and false means to enable more analyzer restrictions. The flags would be better (more consistently) named avoid-infer-dynamic and void-static-cast.
(It made more sense when there was a strong-mode flag, and these flags detracted from that flag in some sense, so you could read it as "+ strong mode, - dynamic casts". Now that strong mode is Dart, having analyzer flags detract from the language is less understandable).

lrhn · 2018-03-22T07:31:42Z

src/_guides/language/sound-dart.md

+  The terms **sound** Dart and **type safe** Dart
+  are often used interchangeably.
+  You might also see the term **strong mode**.
+  Strong mode was an opt-in Dart 1.x feature


Just "Dart 1 feature". Saying "1.x" seems curious when we should know exactly which "x" it applies to. We could say "Dart 1.19+" (number picked out of thing air).

lrhn · 2018-03-22T07:32:52Z

src/_guides/language/sound-dart.md

+  Not all tools have been updated to fully support
+  the sound static type system.
+  For example, dart2js and tools that depend on dart2js
+  (such as DartPad)


That should change real soon now, right?
(Depending on our DartPad resources, it tends to be behind by quite a bit).

lrhn · 2018-03-22T07:34:33Z

src/faq.md

 With strong mode enabled (in an implementation that has both the
-static and runtime checks), Dart is a statically typed language ensuring
+static and runtime checks), Dart 1.x is a statically typed language ensuring


Just "Dart 1".

We've been saying 1.x consistently in the docs. If we change it here, we'll have to change it everywhere.

@mit-mit / @anders-sandholm / @timsneath, are we switching from Dart 1.x to Dart 1?

To be honest, I don't think it's particularly worth the painstaking work to fix this up throughout the site. (I'd prefer to spend the time filling out some of the other doc gaps.) In a few months' time, I suspect we'll be gradually removing most references to Dart 1.x anyway, as Dart 2 becomes the only supported version of the language in common usage.

lrhn · 2018-03-22T07:59:50Z

src/_guides/language/sound-dart.md

@@ -418,14 +363,14 @@ using `var`, the resulting map has type Map<String, Object>.



The "Map<String, Object>" just above doesn't need escapes or code quotes?

Yikes, good catch.

lrhn · 2018-03-22T08:01:38Z

src/_guides/language/sound-dart.md

@@ -434,6 +379,8 @@ var arguments = foo['args'];

 The resulting definition depends on the type of `foo` and


The type of arguments depends on ...

Not sure what "definition" covers (did it mean "declaration"?)

lrhn · 2018-03-22T08:03:33Z

src/_guides/language/sound-dart.md

+**[PENDING: That's unclear. Why isn't it `List<String>`?
+  `foo` used to be `methodCall`, if that helps.]**
+{% endcomment %}
+


I think it's confusing to use foo before it's introduced. Even in the previous example.
I can't see what the example is trying to say, so either figure that out, or remove it entirely.

lrhn · 2018-03-22T08:09:32Z

src/_guides/language/sound-problems.md

@@ -607,8 +542,8 @@ Do we have any known issues or bugs to list here?
 ### The covariant keyword

 Some (rarely used) coding patterns rely on tightening a type
-by overriding a parameter's type with a subtype, which is illegal in strong
-mode Dart. In this case, you can use the `covariant` keyword to
+by overriding a parameter's type with a subtype, which is illegal.


I prefer "invalid" to "illegal". Just personal peeve, but I don't consider us qualified to pass actual laws. We just get to define what is validly Dart.

lrhn · 2018-03-22T08:11:15Z

src/_guides/language/sound-problems.md

-by overriding a parameter's type with a subtype, which is illegal in strong
-mode Dart. In this case, you can use the `covariant` keyword to
+by overriding a parameter's type with a subtype, which is illegal.
+In this case, you can use the `covariant` keyword to
 tell the analyzer that you are doing this intentionally.
 This removes the static error and instead checks for an invalid
 parameter type at runtime.


"parameter type" -> "argument type"
(We generally use "parameter" about the formal parameters declared by a function and "argument" about actual parameters passed to the function by a function call).

anders-sandholm · 2018-03-22T12:12:43Z

Thanks @kwalrath !
Overall, looks really good. A vast improvement to the site, solidly bringing us to the new epoch of Dart 2!

I'm checking on whether I need to add strong-mode: true back to the analyzer docs.

bwilkerson · 2018-03-23T14:05:23Z

src/_guides/language/analysis-options.md

+Do we still require strong-mode: true to make the analyzer using Dart 2 semantics?
+Will these flags still appear under strong-mode in Dart 2.0?
+Should we mention related command-line flags
+(--no-implicit-casts, --no-implicit-dynamic)?**


For a short time, we will be living in a mixed world and I believe that strong mode will not be the default. Longer term, the flag should go away and, if we still want the "implicit-casts" and "implicit-dynamic" flags they should probably be moved out from under "strong-mode".

I don't know whether those flags will remain long term, but if they do, then we should probably document them.

kwalrath · 2018-03-23T21:40:53Z

Ready to go?

mit-mit · 2018-04-04T20:10:40Z

@kwalrath is this "live"? I don't see the changes https://www.dartlang.org/guides/language/sound-dart ?

kwalrath · 2018-04-04T20:15:26Z

It's in the master branch, which you can see at https://dartlang-org-staging-1.firebaseapp.com/guides/language/sound-dart. We'll switch www.dartlang.org to the master branch once Flutter switches to Dart 2.

We've avoided updating the 1.x branch, except for crucial changes.

To see more about the status (or get the URL for the Dart 2 version of dartlang.org), go to the meta issue, #637.

mit-mit · 2018-04-04T20:19:55Z

Got it, thanks!

kwalrath added 2 commits March 21, 2018 09:43

Strong mode -> sound Dart

26dee2f

Interim save

Expunge references to strong mode

31487c0

kwalrath requested review from chalin and bwilkerson March 21, 2018 20:28

googlebot added the cla: yes Contributor has signed the Contributor License Agreement label Mar 21, 2018

chalin mentioned this pull request Mar 21, 2018

[Meta] Site changes for Dart 2 #637

Closed

63 tasks

chalin reviewed Mar 21, 2018

View reviewed changes

lrhn reviewed Mar 22, 2018

View reviewed changes

incorporate reviewer feedback

8ff3ed4

I'm checking on whether I need to add strong-mode: true back to the analyzer docs.

bwilkerson reviewed Mar 23, 2018

View reviewed changes

kwalrath added 3 commits March 23, 2018 14:34

Fix a test by updating error output

6db6f89

Add back strong-mode:true

15ee115

Tweak dart-2 page

cb1b3de

kwalrath mentioned this pull request Mar 23, 2018

Embed analyzer error in analysis-options #697

Closed

kwalrath merged commit 6314263 into master Mar 23, 2018

kwalrath deleted the sound-dart branch March 23, 2018 23:57

kwalrath mentioned this pull request Jan 4, 2019

Update analysis-options for Dart 2 #689

Closed

		@@ -146,43 +133,27 @@ String s = o; // Implicit downcast
		String s2 = s.substring(1);

		@@ -183,35 +145,26 @@ A sound type system has several benefits:
		code is much less efficient.

		@@ -418,14 +363,14 @@ using `var`, the resulting map has type Map<String, Object>.

		@@ -434,6 +379,8 @@ var arguments = foo['args'];

		The resulting definition depends on the type of `foo` and

No more "strong mode" #694

No more "strong mode" #694

Conversation

kwalrath commented Mar 21, 2018

chalin 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

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

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

kwalrath commented Mar 21, 2018

kwalrath commented Mar 21, 2018

mit-mit commented Mar 22, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lrhn Mar 23, 2018 • 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

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

anders-sandholm commented Mar 22, 2018

Choose a reason for hiding this comment

kwalrath commented Mar 23, 2018

mit-mit commented Apr 4, 2018

kwalrath commented Apr 4, 2018

mit-mit commented Apr 4, 2018

lrhn Mar 23, 2018 •

edited

Loading