Should "augment" be optional?

[munificent]

The augmentations proposal currently says that the introductory declaration can't be marked augment and all augmenting declarations must be.

It's unambiguous that an augmenting declaration is augmenting: it has the same name as a previous declaration in the same augmentation context. That means we could make the keyword optional or eliminate it entirely. Should we?

Personally, I do like having it be explicit. Say you were to write:

class SomeVeryLongName { ... }

// Much later...

class SomeVeryLongName { ... }

You meant the latter to be an unrelated class but accidentally used the same name. If we allow implicit augmentation, instead of a simple name collision error, you'll get a cascade of errors for every part of the class that doesn't overlap properly. If, for example, they both happen to define methods with the same name but different signatures, you'll get errors in those methods. Perhaps worse, if they don't overlap, you'll just silently create one class that is the Frankenstein amalgamation of both.

I don't think augment is much ceremony and avoids those pitfalls. But I could be persuaded otherwise.

[lrhn]

My reason for wanting to make augment optional is that requiring it in every declaration except the first introduces an entirely syntactic dependency on ordering.

If I have two, or more, parts of a class, and every member can have at most one implementation, then order of the parts only matter if I add mixins, and then only if those mixins are order dependent. Most of the time, order doesn't matter.

So most of the time, I can freely move parts around, and even reorder part directives ... except if I swap the first part with another, then I have to add an augment to one part and remove it from another.

The parts are symmetric, but we force you to move around a special (lack of a) marker when you move the first declaration.

I want a way to avoid that problem, for the same reasons that we allow trailing commas (to avoid a lack of a special marker on only the last element of a list).
We can either allow augment on the first declaration too, or allow not having it on other decorations, or both.

I suggest "both".

Make augment optional, and allow the first declaration too have it too.
The only way to get an error is to have augment on a single declaration, with no other declaration of the same name in the same augmentation scope. (Don't say augment if you don't actually augment. You probably typo'ed a name!)

And someone will then definitely ask for a lint to have augment on all the declarations, if there is more than one.
(Like annotate_overrides this would be annotate_augments, even if it's optional.)

Then there will likely be two schools, two styles: "Never use augment" and "Always use augment". I don't expect to see "use augment except on the first declaration" as a style anyone would actually use.

That's another hint to me: If we make augment completely free. You can use it or not use it freely, then I predict only those two dominant styles.
If we enforce one style, and it's different from both of those, I don't think we are giving people what they actually want.

We could also consider using part instead of augment. When you can't stack implementations, it feels more like separate symmetrical part declarations, than it does a layering of augmentations.

[munificent]

This is a really compelling argument. You're right that it introduces a pointless asymmetry. With augmentations, the introductory declaration is just as incomplete as the augmenting ones.

Then there will likely be two schools, two styles: "Never use augment" and "Always use augment". I don't expect to see "use augment except on the first declaration" as a style anyone would actually use.

An argument for the second style is that it means when looking at the introductory declaration, you know there may be other fishy stuff going that isn't obvious from that one declaration.

In this case, I think we should probably use partial. It will be more familiar to users coming from C#, and it's a generally more common word (about 10x more common according to Google Ngram viewer).

[rrousselGit]

Then there will likely be two schools, two styles: "Never use augment" and "Always use augment". I don't expect to see "use augment except on the first declaration" as a style anyone would actually use.

Then the keyword is incorrectly named IMO.
If all declarations are named with 'augment', then that's more of a part class than augment class

augment means "update an existing declaration". But part means "this declaration is defined in multiple pieces"

---

I think it's also important to keep in mind code-generation.

If it's stylistic to write either of:

@annotation
augment class A{}
// OR
@annotation
class A{}

But all declarations must match this style, then the stylistic choice leaks inside generated code.

Given:

@annotation
augment class A{}

Generated code has to generate:

augment class A {...}

But for

@annotation
class A{}

Generated code has to generate:

class A {...}

That sounds like an unnecessary complication.

---

Also, if the keyword is optional: Do we need it at all? Similarly to @override, can't augment be an annotation?

@augment
class A{}

[lrhn]

I wouldn't require generated code to generate a specific style, the two styles are just styles, not requirements. I just don't expect anyone to hand-craft code that uses augment on one declaration and not on another. Generated code can do whatever it likes, and I'd prefer if style checkers don't complain about generated code.

(Not that it's particularly hard for a code generator to check what the existing declaration does, and do the same thing.)

[munificent]

The parts are symmetric, but we force you to move around a special (lack of a) marker when you move the first declaration.

Thinking about this more, I'm not sure I still agree with it.

When I'm writing code, defining a new thing is a deliberate action I might take. Modifying or an extending an existing thing is also an action I might take. At that point in time, I definitely know which action I'm taking.

If a user writes class Foo { ... it's hard for me to imagine them thinking "I don't really know or care if there's a Foo in this library already. If there isn't, here's a new one. If there is, I guess it's fine to add this stuff to it."

Given that, it seems reasonable to me for there to be distinct syntaxes for those operations. It would be weird if there was no way to say, "I want a new class and tell me if it collides with another one."

I'm OK with the current proposal.

It has the nice benefit that it minimizes the ceremony for declarations that are modified by code generation. You just write class Foo { ... . Of course, it has the drawback that you can't tell from the introductory declaration that it's incomplete. In practice, though, I suspect that most of them will, as Remi notes, have some metadata annotation on them that sends a signal to the reader that other stuff is happening.

[lrhn]

I can imagine having two different class declarations that both add members to the same class, without needing one of them to be before the other. They really are symmetric.

I can see the problem with declaring two classes with the same name accidentally.

So, suggestion: Make the keyword be part (it's shorter and symmetrical) and require it on all declarations that have more than one syntactic declaration.

Then you can move around parts without needing to add or remove a keyword.

That runs into the use-case of a user written class work generated augments. There you need to know how the code generation works, and you have to write part. So that sucks.

Second suggestion: Still use part, and allow at most one of a group of coinciding declarations to be without the keyword, but it doesn't have to be the first one.

Then you can write part in front of all your partial declarations if you prefer that, you can omit it if you write only one declaration, allowing code generation to implement that signature using a part declaration or a mixin, and you can omit it from the first declaration of that's how you think of it. but you can also move around parts without having to move the non-part around.
If you give it weird to have the non-marked declaration not be first, you can just write part on front of that too, removing the issue in the future.

(In sure there'll be lots for particular styles. We don't have to decide what the best style is up front.)

[munificent]

We discussed this at the language meeting today. There are basically two orthogonal questions:

1. Which declarations can/must/can't have a modifier on them?
2. What modifier do we use (augment, part, partial, etc.)

We're focused on the question and I'm fairly confident that the answer we pick for that will help us pick a keyword. So in the examples here, I'll use the placeholder keyword We discussed five options:

1. Omitted on first declaration, mandatory on others:

   class C {}
   keyword class C { void foo(); }
   keyword class C { keyword void foo(); }

   This is the current proposal. It is zero ceremony for the introductory declaration. That does mean that if you look at an introductory declaration, you can't immediately tell that there may be other augmentations affecting it.

2. No modifiers at all on any declaration:

   class C {}
   class C { void foo(); }
   class C { void foo(); }

   This is as low-ceremony you could possibly get. But it has the flaw that if you accidentally have two unrelated declarations with the same name, it will attempt to merge them. Any errors you get from that will likely be incomprehensible.

   We agreed to *not do this approach.

3. Optional modifier on any declaration:

   class C {}
   keyword class C { void foo(); }
   class C { keyword void foo(); }

   You can put the modifier on the first declaration, any augmenting ones, all, some, or none. Users can have as little or as much ceremony as they want. The flaw here is that if you don't see a modifier on a declaration, that doesn't tell you anything. It doesn't reliably mean that the declaration complete. Conversely, if you do see the modifier, that doesn't tell you anything either. It could still be the only declaration with that name.

   We agreed to not do this approach.

4. Mandatory modifier on all declarations:

   keyword class C {}
   keyword class C { keyword void foo(); }
   keyword class C { keyword void foo(); }

   This is C#'s approach with partial classes. It is explicit and clear. If you see a declaration with no modifier, you know it's a complete declaration. If you see a declaration with a modifier, you know there must be others.

   However, it places some mandatory ceremony on the introductory declaration. For the use case of code generators where there will likely already be some kind of metadata annotation on the introductory declaration to trigger the code generator, an extra keyword there potentially seems redundant.

   This approach may also help us resolve another open issue: should there be a distinction between abstract (for overriding) and incomplete (for augmenting) member declarations (Should we disambiguate abstract and incomplete functions? #4363)? Currently the answer is "no", and we overload a method declaration with a ; to mean either abstract or incomplete. A mandatory keyword for incomplete declarations would make that unambiguous.

   On the other hand, that ambiguity could be useful. If the introductory declaration has a method with no body, a code generator could either fill in that method by adding an augmenting declaration or by adding a with clause to apply a mixin that implements that method. It's really an implementation detail of the code generator as to how that method ends up with a body. Making the introductory declaration syntax explicitly distinguish abstract and incomplete takes that freedom away from code generators.

5. Mandatory on all but one of the declarations:

   keyword class C {}
   class C { keyword void foo(); }
   keyword class C { void foo(); }

   Sort of a combination of some of the previous options. You can apply the keyword to all declarations (like option 4), or you can omit it on the first one (like option 1), or you can omit it on exactly one of the augmentations.

   This gives you the freedom to treat all of declarations symmetrically (like option 4) or to make the introductory declaration special with minimum ceremony (like option 1), or make... one of the other ones low ceremony. I'm not sure exactly what the motivation for that third bit is. @lrhn would be able explain better.

   It also has many of the downsides of the various approaches. The presence or absence of a keyword doesn't provide an unambiguous signal to the reader. Users now have to decide what style they prefer for which declaration to omit the keyword on, if any.

We haven't reached a conclusion yet. The options still on the table are the current approach, the C# approach, or the last hybrid option.

We'll keep discussing it.

[rrousselGit]

When looking at this, I'm mainly worried about having to use the keyword on class members.
I don't care about keyword class A{}. But keyword void foo() inside classes feels odd.

---

IMO 1. is the ideal in terms of usability.

The 'it's unclear that the class is augmented' is IMO a non-issue when we consider:

• There's hardly any generator out there that doesn't require placing an annotation on the class to augment.
  So we actually have:

  @annotation
  class Example {}

  The annotation is already a context clue that the class will be augmented.
• IDEs likely would generate a codelense such as "go to augmentation". We had one of those with the macro experiment.
  So that too is another context clue.

---

In 4., does that mean that all user-defined methods would have to specify keyword too? If so, that's too much for me.

I personally want to augment user methods in some of my code-generators:

@riverpod
class Example {
  @mutation
  int doSomething() => 0;
}

....
augment class Example {
  int doSomething() {
    try {
      final value = augmented();
      _report(value);
      return value;
   } catch {
     _reportError(value);
     rethrow;
   }
  }
}

It would be a real pain if users had to add part on all methods too.
... Although from the previous discussions, the augmented() inside functions may also be going away ... So I'm not sure how I'd implement this using augmentations without augmented() 🤷

[lrhn]

The reason for allowing up-to-one declaration without a keyword, but not requiring it to be the first, is to allow for the coffee generator use-case without a keyword (so one declaration without keyword), still protect against accidentally making two declarations the same (so at most one unmarked declaration) and not introducing any ordering requirement.

The language cannot distinguish that scenario from handwritten code with multiple declarations, it only sees the code after code generation has completed.

Member declaration order doesn't matter.
If you swap the order of two part files, perhaps because you renamed a file and is sorting part directives, it feels weird that you now need to move a keyword from one file to another just to satisfy an ordering relation that has no effect anyway.

Also, it allows a code generator to decide where to add its extra code. It can add a part directive with an augmenting part class, without being limited to placing it after all existing declarations.

I did a writeup of how that could be specified, with minimal requirements on, well, anything: No ordering requirements, modifiers must be repeated, most other details can be written only once, in any declaration, but must agree if repeated.
(I think I'll adapt that to something that is less permissive for member declarations, fx requiring types on every declaration, because you probably won't have more than two declarations anyway - one abstract and one implementation - and the abstract one will be there to show the types, so it really just means that the implementation must repeat that type, which is good for readability, and not that cumbersome.)

I now think that requiring the unmarked declaration to be the "first" declaration (in the generalized source ordering) is acceptable (or in above-ordering, see next comment).
Code generators will likely be OK with adding their augmentations after the existing declarations, they're automated tools so they'll adapt to any requirement we give them.
The fix for user-written declarations, if they get out of order, is to put the keyword on all the declarations. Like adding the trailing comma to all lines, when you've done that once, the ordering problem goes away in the future.

If we have lints that can distinguish generated code from handwritten code, I'll expect a lint that requires keywords on all of multiple handwritten declarations, and that maybe requires omitting the keyword if there is only one non-generated declaration. (I expect that to be the style I'd personally use for "properly written code", and small hacky scripts don't get linted anyway.)

[lrhn]

Based on talking to @leafpetersen, one reason it can feel arbitrary that the first declaration can omit the keyword, is that being "first" in the generalized source ordering can itself feel arbitrary.
We have a defined ordering between sibling parts, but it is an accident of source ordering.

What if being first meant that the declaration must be above all other declarations?
(Using the partial above/below ordering of the enhanced parts specification, rather than the complete before/after relation, where a declaration is above later declarations on the same file, and above all declarations in parts of that file, but it's not above or below declarations in sibling files.)

So define: a declaration is introducing if it is above all other declarations for the same entity. Only an introducing declaration can omit the keyword.

There can be at most one introducing declaration for a name, and if there is only one declaration for a name, it's trivially introducing.
If you have declarations only in sibling parts, neither is introducing, and both/all must have the keyword.

Then the introducing declaration will not change by reordering part files, or by sorting members in a file (if the sorting is stable).

I still wouldn't require the introductory declaration to be complete (in either sense), but we could say that you cannot omit types or type parameters from an un-keyworded declaration. You can omit implementation, and you can add class-like declaration headers later (they're like the "implementation of a class" details).

The issue with this is that code generators must then put their code below the introducing declaration, which may require multiple files for a single library, up to one per leaf part file. It can't just put it all in one final part of the library file (which would be after all existing declarations of that library, but only below the declarations of the library file itself).

I guess a sufficiently smart code generation framework can handle the details, so the code generator logic can just say which declaration it wants to augment - if augmenting an initializing declaration, the augmentation can be put in a new final part file of the initializing declaration's file. (It could try to find the final-most transitive part file below that file, to combine declarations for every initializing declaration on that path in one file, but that risks running into a configurable part directive, and then it'll have to stop there anyway. And that's assuming that code generation creates new files - it could also write directly into the original file (suitably delimited by some kind of "GENERATED BY" comments, so it can be updated later).

[munificent]

What if being first meant that the declaration must be above all other declarations?

Ooh, I like this.

So define: a declaration is introducing if it is above all other declarations for the same entity. Only an introducing declaration can omit the keyword.

There can be at most one introducing declaration for a name, and if there is only one declaration for a name, it's trivially introducing. If you have declarations only in sibling parts, neither is introducing, and both/all must have the keyword.

Then the introducing declaration will not change by reordering part files, or by sorting members in a file (if the sorting is stable).

Oh, interesting. I was assuming that you always needed to have an introducing/introductory declaration. But what you're proposing here is that there are a few valid structures:

Trivial, solitary declaration.

class Foo {}

Main unmarked declaration above augmentations

// main.dart
part 'a.dart';
part 'b.dart';

class Foo {} // Or could write `augment` here it wanted.

// a.dart
augment class Foo {}

// b.dart
augment class Foo {}

C#-style symmetric all marked partial declarations

// main.dart
part 'a.dart';
part 'b.dart';
part 'c.dart';

// a.dart
augment class Foo {}

// b.dart
augment class Foo {}

// c.dart
augment class Foo {}

I'm not deeply opposed to this, but I do wonder if it's more generality than we need. Aside from you personally, @lrhn, do we know if there are a significant number of users who care about organizing code using the third style here?

Personally, I could live without that. But then I would be happy to keep the current proposal around this. :)

Would it not be sufficient to say that if you want to write in that C# style... just add an empty introducing declaration in the parent file?

The issue with this is that code generators must then put their code below the introducing declaration, which may require multiple files for a single library, up to one per leaf part file. It can't just put it all in one final part of the library file (which would be after all existing declarations of that library, but only below the declarations of the library file itself).

Oh, that is an issue. It would suck if moving a piece of hand-authored code from the main library to a hand-authored part broke a code generator.