[dart-misc] Style guide suggestion: type annotating initializing formals

[Sean McCleary]

Hello all,

I've got a suggestion for the dart style guide, and I'm not really sure
where to pitch it. If I ought to take this somewhere else, someone wanna
point me in the right direction?

Specifically, it's about this rule: "DON’T type annotate initializing
formals."

The example in the documentation shows this as the correct way:

class Point {
int x, y;
Point(this.x, this.y);
}


That's fine. If you wanna tell me it'd be redundant or error-prone to
repeat the type of x and y, then OK. A consumer of the Point class can
clearly see, via the class's public interface, what the type of "x" and "y"
are.

However, when the class members are private, that's not the case. Consider
this:

class DemoClass {
String _someVar;


/// Instantiates a DemoClass
DemoClass(this._someVar);
}


In this example, _someVar is a private class member. As a consumer of this
class, I should not have to look at its private implementation details in
order to know the expected type of the constructor parameters. The method
signature of the constructor should provide me with that information.

Sure, dart's an interpreted language, so I could crack open the DemoClass
file and hunt through its private members to find the type of _someString.
Or, if the author of the class was kind enough to provide some generated
documentation, I could go look it up there. Or I could use the analysis
server to maybe not even worry about it.

But that all seems very out of line with (what I understand to be) dart's
philosophy -- that code should be clear in order to facilitate the building
of large applications by large teams. Having to dig through the code of a
class or module just to be able to use it because it doesn't provide a
clear public interface, or having to rely on external tools, is the kind of
thing that I think drives people _away_ from languages like JavaScript and
hopefully _towards_ dart.

So anyway, there's my suggestion.

Sean

[Günter Zöchbauer]

While I think the reasoning is valid I think it's too weak of a point to
change anything.
If I use code navigation to investigate details I don't care if it's a
public or private variable I navigate to.
When I look up the API docs I assume the constructor parameter type is
shown without a need to navigate to the private field (don't use generated
API docs a lot)

I don't see a real benefit of adding a type there and it's just redundant
work and makes it less obvious that it's a `this.xxx` kind of constructor
parameter.

Post by Sean McCleary
Hello all,
I've got a suggestion for the dart style guide, and I'm not really sure
where to pitch it. If I ought to take this somewhere else, someone wanna
point me in the right direction?
Specifically, it's about this rule: "DON’T type annotate initializing
formals."
class Point {
int x, y;
Point(this.x, this.y);
}
That's fine. If you wanna tell me it'd be redundant or error-prone to
repeat the type of x and y, then OK. A consumer of the Point class can
clearly see, via the class's public interface, what the type of "x" and "y"
are.
However, when the class members are private, that's not the case.
class DemoClass {
String _someVar;
/// Instantiates a DemoClass
DemoClass(this._someVar);
}
In this example, _someVar is a private class member. As a consumer of
this class, I should not have to look at its private implementation details
in order to know the expected type of the constructor parameters. The
method signature of the constructor should provide me with that
information.
Sure, dart's an interpreted language, so I could crack open the DemoClass
file and hunt through its private members to find the type of _someString.
Or, if the author of the class was kind enough to provide some generated
documentation, I could go look it up there. Or I could use the analysis
server to maybe not even worry about it.
But that all seems very out of line with (what I understand to be) dart's
philosophy -- that code should be clear in order to facilitate the building
of large applications by large teams. Having to dig through the code of a
class or module just to be able to use it because it doesn't provide a
clear public interface, or having to rely on external tools, is the kind of
thing that I think drives people _away_ from languages like JavaScript and
hopefully _towards_ dart.
So anyway, there's my suggestion.
Sean

['Bob Nystrom' via Dart Misc]

The method signature of the constructor should provide me with that
information.

I agree.

How is it that you're viewing the signature of the contructor? If you're
navigating to its actual definition, then you'll already within the
implementation of the class and a bit of scrolling will reveal the type.

If you're, say, hovering over a constructor invocation in the IDE, I would
hope that it shows the type of the parameter by inferring it from the field
type.

Likewise, a good doc generator should use the type of the field to show the
parameter's type.

The way I look at it, the constructor parameter *is* typed. The user has
written down a type already, at the field declaration. There's no value in
making a human write the same thing again elsewhere. We just need to make
sure our tools take that already-written type and present it to users of
the constructor in all the right places.

Cheers!

– bob

[Sean McCleary]

I suppose my main point is, that in this language which purports to provide
clarity via types and interface, so that large codebases won't fall apart
the way they do in other popular languages, it seems counter-intuitive that
the officially-recommended way to create a class in this situation provides
no indication of what the constructor's parameter types are via the class's
public interface to the rest of the world. Providing a public interface
which tells me, the consumer of that class, everything I need to know in
order to use it seems like the correct way to use the language, without
having to rely on external tools to do it for me.

Yes, I can open the class definition and track down those private members
and see their type if I need to, and I can do that without relying on
external tools. But that feels counter to the philosophy of encapsulation.
It also seems like just a happy coincidence of the dart runtime; there is
no guarantee that dart the *language* will always be used in an environment
where the dependencies' source code is available and interpreted. (Does
flutter actually compile it to something native? I'm not really sure; but
you get my point: being able to navigate to any class and view its source
isn't a guarantee of dart *the language* so the *language style guide* shouldn't
assume it is.)

Yeah, declaring the type twice (once for the private class member and once
for the constructor parameter) doesn't seem perfect, but IMO omitting the
type from the method signature and thereby failing to provide consumers
with a complete public interface for the class feels *more wrong* to me.

Anyway, you get me I'm sure. And I realize I might be getting more
philosophical than practical here. If I'm in the minority, I'd still at
least suggest updating the style guide to make it clear that it also
applies to private class members. Currently the examples only show public
class members, and someone else might find it counter-intuitive for private
members and want some clarity there.

Sean

Post by 'Bob Nystrom' via Dart Misc

The method signature of the constructor should provide me with that
information.

I agree.
How is it that you're viewing the signature of the contructor? If you're
navigating to its actual definition, then you'll already within the
implementation of the class and a bit of scrolling will reveal the type.
If you're, say, hovering over a constructor invocation in the IDE, I would
hope that it shows the type of the parameter by inferring it from the field
type.
Likewise, a good doc generator should use the type of the field to show
the parameter's type.
The way I look at it, the constructor parameter *is* typed. The user has
written down a type already, at the field declaration. There's no value in
making a human write the same thing again elsewhere. We just need to make
sure our tools take that already-written type and present it to users of
the constructor in all the right places.
Cheers!
– bob

[Lasse R.H. Nielsen]

Post by Sean McCleary
I suppose my main point is, that in this language which purports to
provide clarity via types and interface, so that large codebases won't fall
apart the way they do in other popular languages, it seems
counter-intuitive that the officially-recommended way to create a class in
this situation provides no indication of what the constructor's parameter
types are via the class's public interface to the rest of the world.

But it *does* declare the type of the parameters. It's not written into the
code, but the type is clearly defined, and *tools* should show the correct
type. The API docs do show the correct type. I don't know if the analysis
server does, but it should.

Post by Sean McCleary
Providing a public interface which tells me, the consumer of that class,
everything I need to know in order to use it seems like the correct way to
use the language, without having to rely on external tools to do it for me.

I actually think it's the other way around - the tool generated
documentation should show you what you need to do, you shouldn't have to
look at the actual code.

Post by Sean McCleary
Yes, I can open the class definition and track down those private members
and see their type if I need to, and I can do that without relying on
external tools. But that feels counter to the philosophy of
encapsulation. It also seems like just a happy coincidence of the dart
runtime; there is no guarantee that dart the *language* will always be
used in an environment where the dependencies' source code is available and
interpreted. (Does flutter actually compile it to something native? I'm
not really sure; but you get my point: being able to navigate to any class
and view its source isn't a guarantee of dart *the language* so the *language
style guide* shouldn't assume it is.)

Exactly. That's why you shouldn't depend on the *source*, but on the class
API, which should be available and should show you the correct types,
whether written explicitly or inferred.

Post by Sean McCleary
Yeah, declaring the type twice (once for the private class member and once
for the constructor parameter) doesn't seem perfect, but IMO omitting the
type from the method signature and thereby failing to provide consumers
with a complete public interface for the class feels *more wrong* to me.
Anyway, you get me I'm sure. And I realize I might be getting more
philosophical than practical here. If I'm in the minority, I'd still at
least suggest updating the style guide to make it clear that it also
applies to private class members. Currently the examples only show public
class members, and someone else might find it counter-intuitive for private
members and want some clarity there.

Now, as a personal pet peeve, I fully and heartily discourage using
initializing formals with private members.
If it's some internal class of your application, you can do whatever you
want, but if its part of your package or library's *public* API, the
parameters should have *public* names, not private ones. That means:
Foo(String bar) : _bar = bar;
rather than
Foo(this._bar);
Don't be lazy here!

/L
--
Lasse R.H. Nielsen / ***@chromium.org
'Faith without judgement merely degrades the spirit divine'

[Sean McCleary]

But it *does* declare the type of the parameters. It's not written into
the code

I guess, central to my stance, is the idea that something does have to be
"written into the code" in order to be "declared".

, but the type is clearly defined, and *tools* should show the correct
type. The API docs do show the correct type. I don't know if the analysis
server does, but it should.

Right, -- and look, I'm not trying to be argumentative here, I totally get
your point, I'm just making sure that you get mine -- I keep saying that
one shouldn't *have* to rely on external tools in order to know a class's
public interface. The language in and of itself should tell me the public
interface. So there is maybe a discussion to be had about whether having
to rely on external tools in order to get a class's public interface is
*acceptable* or not, but I do understand that it's *possible* (but would
like to see a solution where it's not necessary).

Now, as a personal pet peeve, I fully and heartily discourage using
initializing formals with private members.
... if its part of your package or library's *public* API, the parameters

Well it sounds like you find it just as distasteful as I do! You because
you've exposed a private class member name to the outside world (which,
personally, doesn't bother me), and me because the constructor's method
signature doesn't tell you the expected type of the parameter. Writing it
the way you propose:

MyClass(String someString) : _someString = someString;

...is a good suggestion. I like it. Thanks. It complies with the style
guide and alleviates my concern about the constructor's method signature.
Though I will point out that it does require one to list the type twice:
once for the private class member and once for the constructor parameter.
And while that, specifically, doesn't seem to be a problem for either you
or I, the avoidance of such is, as I understand it, the whole motivation of
this style rule in the first place. And that while "someString" and
"_someString" are technically two different variables, this seems to be
very much following the* letter* of the rule and not the *spirit *of the
rule. That is to say, any arguments which one could make in favor of this
style rule would also apply to the way you suggest doing it. If I
understand everything correctly. (Which, admittedly, I might not.) Also
that doing it the way you suggest when initializing *private* class members
but using the initializers for *public *class members is inconsistent.

I like dart. I like that it doesn't require a bunch of external tools like
node, or have a lot of baffling "magic" going on as is common in Ruby of
PHP. Clarity and simplicity to facilitate conceptual integrity, yessir. I
feel like the suggestions to use an external tool, or just close my eyes
and accept that the constructor parameters *are* typed even though I can't
*see* it, are kinda going in that bad direction. But, OK, I get that not
everyone agrees. Good points here. For my part, I'll probably just do it
the way you suggested (at least until the linter is mature enough to let me
disable the check for this rule).

Thanks all
Sean

[tatumizer-v0.2]

Post by Sean McCleary
And while that, specifically, doesn't seem to be a problem for either you

or I, the avoidance of such is, as I understand it, the whole motivation of
this style rule in the first place. And that while "someString" and
"_someString" are technically two different variables, this seems to be
very much following the* letter* of the rule and not the *spirit *of the
rule

Just wondering: haven't you been reading too much Kafka recently?

Really enjoyed the exchange though. I wish I could express myself with such
exquisite eloquence.

Good job!

[kc]

Alex, have you read Pale Fire?

K.

Post by Sean McCleary
And while that, specifically, doesn't seem to be a problem for either

you or I, the avoidance of such is, as I understand it, the whole
motivation of this style rule in the first place. And that while
"someString" and "_someString" are technically two different variables,
this seems to be very much following the* letter* of the rule and not the
*spirit *of the rule
Just wondering: haven't you been reading too much Kafka recently?
Really enjoyed the exchange though. I wish I could express myself with
such exquisite eloquence.
Good job!

[kc]

I agree. The syntax is too magical. The area where Dart could use some
succinctness is with type inference and locals. See Flutter code base.

K.

Post by Sean McCleary
I suppose my main point is, that in this language which purports to
provide clarity via types and interface, so that large codebases won't fall
apart the way they do in other popular languages, it seems
counter-intuitive that the officially-recommended way to create a class in
this situation provides no indication of what the constructor's parameter
types are via the class's public interface to the rest of the world.
Providing a public interface which tells me, the consumer of that class,
everything I need to know in order to use it seems like the correct way to
use the language, without having to rely on external tools to do it for me.
Yes, I can open the class definition and track down those private members
and see their type if I need to, and I can do that without relying on
external tools. But that feels counter to the philosophy of encapsulation.
It also seems like just a happy coincidence of the dart runtime; there is
no guarantee that dart the *language* will always be used in an
environment where the dependencies' source code is available and
interpreted. (Does flutter actually compile it to something native? I'm
not really sure; but you get my point: being able to navigate to any class
and view its source isn't a guarantee of dart *the language* so the *language
style guide* shouldn't assume it is.)
Yeah, declaring the type twice (once for the private class member and once
for the constructor parameter) doesn't seem perfect, but IMO omitting the
type from the method signature and thereby failing to provide consumers
with a complete public interface for the class feels *more wrong* to me.
Anyway, you get me I'm sure. And I realize I might be getting more
philosophical than practical here. If I'm in the minority, I'd still at
least suggest updating the style guide to make it clear that it also
applies to private class members. Currently the examples only show public
class members, and someone else might find it counter-intuitive for private
members and want some clarity there.
Sean

Post by 'Bob Nystrom' via Dart Misc

The method signature of the constructor should provide me with that
information.

I agree.
How is it that you're viewing the signature of the contructor? If you're
navigating to its actual definition, then you'll already within the
implementation of the class and a bit of scrolling will reveal the type.
If you're, say, hovering over a constructor invocation in the IDE, I
would hope that it shows the type of the parameter by inferring it from the
field type.
Likewise, a good doc generator should use the type of the field to show
the parameter's type.
The way I look at it, the constructor parameter *is* typed. The user has
written down a type already, at the field declaration. There's no value in
making a human write the same thing again elsewhere. We just need to make
sure our tools take that already-written type and present it to users of
the constructor in all the right places.
Cheers!
– bob

['Bob Nystrom' via Dart Misc]

The area where Dart could use some succinctness is with type inference and
locals.

Now that we have strong mode, Dart has pretty great type inference
<https://github.com/dart-lang/dev_compiler/blob/master/doc/STATIC_SAFETY.md#type-inference>
of locals along with lambda parameters, type arguments, and even many top
level variables and constants. (I say many because there are some cases
involving circularity where it breaks down.)

Most of our internal users are using strong mode now, and the feedback we
get is overwhelmingly positive.

See Flutter code base.

The Flutter folks don't rely on type inference and prefer to annotate
things explicitly.

Cheers!

– bob

[Istvan Soos]

On Mon, Sep 26, 2016 at 6:42 PM, 'Bob Nystrom' via Dart Misc

Post by 'Bob Nystrom' via Dart Misc
Most of our internal users are using strong mode now, and the feedback we
get is overwhelmingly positive.

+1 for `dartanalyzer --lints --package-warnings --fatal-lints
--fatal-warnings --fatal-hints --strong`

Cheers,
Istvan

[Günter Zöchbauer]

Post by Istvan Soos
On Mon, Sep 26, 2016 at 6:42 PM, 'Bob Nystrom' via Dart Misc

Post by 'Bob Nystrom' via Dart Misc
Most of our internal users are using strong mode now, and the feedback

we

Post by 'Bob Nystrom' via Dart Misc
get is overwhelmingly positive.

+1 for `dartanalyzer --lints --package-warnings --fatal-lints
--fatal-warnings --fatal-hints --strong`

... or adding an `.analyzer_options` file to your project

Post by Istvan Soos
Cheers,
Istvan

[kc]

Are type annotations/inference used by the AOT Dart VM?

K.

Post by 'Bob Nystrom' via Dart Misc

The area where Dart could use some succinctness is with type inference
and locals.

Now that we have strong mode, Dart has pretty great type inference
<https://github.com/dart-lang/dev_compiler/blob/master/doc/STATIC_SAFETY.md#type-inference>
of locals along with lambda parameters, type arguments, and even many top
level variables and constants. (I say many because there are some cases
involving circularity where it breaks down.)
Most of our internal users are using strong mode now, and the feedback we
get is overwhelmingly positive.

See Flutter code base.

The Flutter folks don't rely on type inference and prefer to annotate
things explicitly.
Cheers!
– bob