Clarify text for unnecessary_final lint

[timsneath]

The unnecessary_final lint contains a controversial explanation of its rationale.

Specifically:

var is shorter, and final does not change the meaning of the code.

The historical context is here: dart-archive/linter#1827

While there are clearly divergent preferences around the use of final, it does change the meaning of the code (as the prefer_final_locals lint explains). And while var is shorter by two characters, that seems like a poor rationale for a lint. Readability is preferred over terseness, anyway.

Lastly, Effective Dart has settled case law on the subject:

State that is not mutable—that does not change over time—is easier for programmers to reason about. Classes and libraries that minimize the amount of mutable state they work with tend to be easier to maintain. Of course, it is often useful to have mutable data. But, if you don’t need it, your default should be to make fields and top-level variables final when you can.

While we don't need to remove the rule, we should have explanatory text that is more accurate. For example, "some people prefer the simplicity of using var for all variables."

[pq]

/cc @davidmorgan

[MelbourneDeveloper]

Thanks @timsneath.

There is nothing wrong with the lint itself. I understand why some teams may want to embrace this. The issue is the documentation, as you say.

var is shorter, and final does not change the meaning of the code.

I looked at this lint and was very confused. This isn't a reason to prefer var over final but it's also just plain wrong.

Some teams may want to reassign variables as a matter of preference. For the record, I think that something like this would be better.

You should make assignments to existing variables where possible to avoid creating multiple variables for the same logical value

and perhaps

var allows for reassignments while final means your code may end up with multiple variable names for the same logical value.

[davidmorgan]

Hi Tim,

Thanks :) this is a fun one.

The Dart team--particularly Bob and Lasse, and they persuaded me, which is why I added this lint--prefer and recommend using varfor locals. Nobody else on the team has a strong opinion as far as I'm aware.

The prefer_final_locals lint description is wrong: the compilers definitely know whether local variables are reassigned, final does not help.

The Effective Dart rule you point to is talking about instance/global state not variables. It says exactly "fields and top-level variables final" ... locals should not be. Again, according to Bob ;)

Unfortunately there is a tendency for people to pick up the "prefer final" lints with a sense that they are recommended and better--they are not. The recommended way is this lint. Unfortunately, the other lints got there first, and are far better established as a result. We might actually have to go with 'final' in google3 just for consistency--and against style recommendations.

I don't think there's any nice resolution possible here; given the strength of feeling from Bob and Lasse I'm pretty sure we will never recommend "final", and given how much better established those lints are I don't think we can ever recommend "var", either.

And in the end it just doesn't matter too much: what matters for the code is instance mutability, as called out in Effective Dart.

Thanks

Morgan

[MelbourneDeveloper]

@davidmorgan the issue is not the linter. The issue is the mistake in the documentation

[MelbourneDeveloper]

I will make a PR for the doco in the next couple of days

[davidmorgan]

Hi Christian,

Those suggestions don't make sense I'm afraid; we definitely don't want to encourage var as any kind of optimization.

Using var is simply the default: it's how the language was intended to be used. This is direct from the language designers ;)

We have repeatedly discussed whether to recommend final for locals and the answer is no.

Thanks

Morgan

[MelbourneDeveloper]

@davidmorgan I wouldn't use this linter if you paid me, but you're not getting it.

The current doco is completely incorrect and confusing

var is shorter, and final does not change the meaning of the code.

final does change the meaning of the code. You can frame the linter however you like. The point of the matter is that it reads like var is just as good as final and that's why this issue is here.

[davidmorgan]

Perhaps "change the meaning of the code" could be clarified.

What was meant was, "does not change the meaning of the code from the compiler's point of view". The code compiles and runs exactly the same with var or final.

It could be argued that it changes the intent of the code for a human reader, and perhaps this can be confused with "meaning"?

Thanks.

[MelbourneDeveloper]

@davidmorgan the reader of this document is not concerned with how the compiler interprets it.

What the reader takes away from this is that var and final mean the same thing, but they don't.

'var' means that the reference can be set multiple times while a 'final' declaration can only be set once.

The documentation is very confusing for people reading the documentation. It is especially confusing for people new to Dart that may not have a full understanding of what the two keywords mean.

[davidmorgan]

Yes, the wording could be improved; suggestions welcome.

[MelbourneDeveloper]

@davidmorgan

I think there's a broader question of how to document the intent of linters here.

I don't like this linter, but I understand the motivation. Many people new to Dart will use var more often than final and actually decide that it's better than final. They may decide to enforce that because of some arbitrary team decision, and that's fine.

The question is how to phrase the intent of the linter without recommending it and possibly explaining that it goes against the Dart recommendations.

To be honest, the linter doco should be more opinionated in order to match the tone of the Effective Dart guide.

[davidmorgan]

Using var, as enforced by this lint, is not quite officially recommended, but it's as close as it can get without being recommended.

Using final for locals is definitely not officially recommended.

The Dart team--particularly Bob and Lasse, and they persuaded me, which is why I added this lint--prefer and recommend using var for locals. Nobody else on the team has a strong opinion as far as I'm aware.

Bob is the author and maintainer of Effective Dart, and he prefers var.

As I said, I'm not aware of anyone on the Dart team who wants to recommend final.

[MelbourneDeveloper]

@davidmorgan well that totally changes the game then.

That's certainly not clear in the linter.

If the Dart team prefers var over final then both the related linters should mention that and put the case forward.

[MelbourneDeveloper]

But the point still stands that var and final are different and the documentation needs to clarify that.