[3.2] Private field promotion docs

[MaryaBelanger]

This is an evaluation ticket

Evaluating the possible need for doc updates due to dart-lang/language#2020

Summary

Type promotion is currently only available for local variables. #2020 will make it possible for class fields to be safely promoted if they meet certain criteria: when the field is private and final (and there are no concrete getters of the same name, in the same library).

Limiting promotable fields to final tells the compiler the instance value can't change (and therefore, type promotion remains sound). But, final doesn't protect soundness if another class implements the original class and overrides its field declarations. So, the compiler scans the library for implementing classes and can prevent type promotion of the original because of it.

But what if a class outside of the library implements the defining class and overrides its fields? The compiler can't check for implementing classes outside of the original's library, which is why the field must also be private. A private field tells the compiler that an implementing class from another library isn't able to change the value.

So private and final allow the compiler to soundly promote a type because they inherently mean the value cannot be overridden outside of the compiler's purview.

One loophole (nosuchmethod overriding interfaces in an implementing class that doesn't fulfill the interface contract, i.e. doesn't explicitly declare the fields of the original class) is covered in #49687 and another evaluation ticket (#4263).

Evaluation

• Fixing type promotion failures

  • [3.2] Update "Fixing type promotion failures" for private final field promo #5246

  • The sections on this page are actually linked to in type promotion error messages.

  • Only local variables can be promoted is no longer an error

  • "Write captured by a local function", "Written outside of the current closure or function expression", "Write captured outside of the current closure or function expression" sections all have "create a local variable" as a solution / workaround, so I'm wondering if they'll still be errors once non-local variables can be promoted, or maybe the workaround will change to utilize private final field promotion

    • "Other causes and workarounds" section also mentions creating a local variable to fix most type promotion issues

  • New sections will need to be added to support new error messages from 2020 (@stereotype441 evaluating actual error code):

    • When non-local field promotion is not allowed because they're using an older version of Dart
    • When promotion doesn't work because the field is not final and private
    • When there's a getter with the same name in the same library that isn't final
      • This comment in 2020 says: "If the user tries to promote a field, and it's not promotable because there's some other concrete instance getter with the same name that's not a final field, we can easily explain to them why the promotion failed. And if they want promotion anyway (and know that it's safe), the workaround should be fairly intuitive: just rename the field."
      • The workaround here is unclear, "just rename the field" is referring to the original field or the getter?
      • wouldn't the getter need to have the same name as the field it's getting?
      • wouldn't the fix be that they need to declare the getter final too?

• Effective Dart
  Implementation draft here: Effective Dart: update type promotion suggestion for private final #4272
  New: [3.2] Update effective dart mention of "only local variables can be promoted" #5324

  • "Unfortunately, promotion is only sound for local variables and parameters, so fields and top-level variables aren’t promoted." - no longer true
  • The entire workaround is technically no longer necessary, maybe the section can be removed?
    • It's still necessary, there are still many cases where type promotion isn't allowed and this is still a workaround for them.
  • Should we add a "CONSIDER" section recommending declaring private final fields if you want type promotion to happen?
    • No, stating it in the existing section instead

• The Dart type system

  • Maybe part of Overhaul and introduce new type system documentation #4745
  • No updates

• Fixing common type problems is another too-similar page that might need to be addressed to not detract from the source of truth that Fixing type promotion failures should be.

  • No updates
  • Put Fixing type promotion failures in the side nav somewhere...
  • MAYBE consolidate? Reconcile and consolidate type issue troubleshooting pages #4393

• Overview (nothing related)

• FAQ (nothing related)

• Codelab

  • Fairly certain there's nothing related, but the examples should probably be tested as-is with private final field promotion active...?
  • [3.2] Very minor changes to null safety codelab #5329

• Understanding null safety:

• [3.2] Understanding null safety page updates for private final field promotion #5325

  • Type promotion on null checks
    • "Note that type promotion only works on local variables, not on fields or top-level variables..."
  • Working with nullable fields
    • E.g. "Flow-based type promotion does not apply to fields because..."
    • The entire section might be a misnomer because it's purpose is to provide a workaround for promoting nullable fields (there's also a "Working with nullable types" section)
  • Lots of minor wording about local-only

References

• Original issue: Enable promotion for private final fields and fields on non-escaping private classes language#2020
• Comment that mostly sums up the final conclusion: Enable promotion for private final fields and fields on non-escaping private classes language#2020 (comment)

[stereotype441]

Minor nit: when you say "and getters of the same name, in the same library, are also final" I think you mean something like "and there are no concrete getters of the same name, in the same library". (There's no such thing as a final or non-final getter).

[MaryaBelanger]

Note: need to take into consideration record fields as well

[parlough]

I don't think you intended to close this as done yet. I'm going to reopen it, but feel free to close if that's what you meant :)

[MaryaBelanger]

@parlough Thanks, that wasn't supposed to happen! 😱 I think it happened because I linked the recent go-link pr to this, and just closed that. But you're right, definitely not anywhere near being done :)