Skip to content

Add 'Primary constructor' to glossary #13033

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sfshaza2 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add 'Primary constructor' to glossary #13033

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions src/data/glossary.yml
View file
Open in desktop
Copy link

@kallentu kallentu Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@eernstg to review as well.

Copy link

@eernstg eernstg Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the heads up!

I'll assume that this glossary entry should describe the primary constructors feature which is about to be released—it doesn't seem particularly useful to have one description of the concept for some weeks, and then updating it substantially to cover the much more general notion of primary constructors that we're about to release.

Original file line number Diff line number Diff line change
Expand Up @@ -291,6 +291,26 @@
- "design"
- "ui"

- term: "Primary constructor"
short_description: |-
A constructor declared as part of the type declaration.
Copy link

@eernstg eernstg Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The phrase 'type declaration' is rather vague. It's often used to designate a type annotation (as in "the variable has a type declaration" when talking about declarations like String s = '';), as well as the meaning which is intended here. It would be nice if we could use a phrase which is more precisely denoting a class declaration, a mixin class declaration, an enum declaration, or an extension type declaration.

Next, a class declaration starts at a keyword (often class, but we can also have final class, sealed class, and the like), and it ends at the final } of the class body (or, with the upcoming enhancements, a semicolon which is the entire class body on its own). This implies that every member declaration is also part of "the type declaration". The new thing is that the primary constructor is part of the header of the class declaration, it's not in the body.

Similarly for mixin class declarations etc.

Perhaps this would work:

Suggested change
A constructor declared as part of the type declaration.
A constructor declared in the header of a class or a similar type declaration.

long_description: |-
A _primary constructor_ is a concise way to declare a constructor
directly in the type declaration.
Copy link

@eernstg eernstg Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
directly in the type declaration.
directly in the header of a class, mixin class, enum, or extension type declaration.


Currently, this feature is only available for [extension types][].
Copy link

@kallentu kallentu Feb 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is inaccurate -- primary constructors can be used for classes, extension types, and enums as well.

It allows you to define the underlying representation object
and bind it to a field in one step.
Comment on lines +302 to +303
Copy link

@eernstg eernstg Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's really great that this glossary entry is so short. It should allow developers to get to know about the concept of a primary constructor. There would be other pages about all the details.

So how do we communicate that the primary constructors of class, mixin class, and enum declarations have a large number of properties in common, and the primary constructors of extension types are different in several ways?

Here is one attempt at saying very little, but still enough to give the reader a relevant hint:

Suggested change
It allows you to define the underlying representation object
and bind it to a field in one step.
A primary constructor in a class, mixin class, or enum declaration is a concise
way to specify a constructor and a number of instance variables in a single
constructor declaration in the header.
A primary constructor in an extension type declaration allows you to define the
underlying representation variable and its type.

We can't even really say "in a single declaration" when it comes to extension types, because they don't support declaring the representation variable using a regular instance variable declaration in the first place. There is simply no other way to declare the representation variable (name and type) of an extension type than having a primary constructor.


[extension types]: https://dart.dev/language/extension-types
related_links:
- text: "Extension types constructors"
link: "https://dart.dev/language/extension-types#constructors"
type: "external"
Comment on lines +297 to +309
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The description for primary constructors is slightly outdated. Since Dart 3.4, primary constructors are also available for classes, not just extension types.

I'd suggest updating the description to include classes and adding a link to the relevant documentation for class-based primary constructors to make the glossary entry more accurate and complete.

  long_description: |-
    A _primary constructor_ is a concise way to declare a constructor
    directly in the type declaration.

    Primary constructors can be used with [classes][] and [extension types][].
    For classes, they allow you to define fields and initialize them from
    constructor parameters in one step. For extension types, they allow you
    to define the underlying representation object and bind it to a field.

    [classes]: https://dart.dev/language/constructors#primary-constructors
    [extension types]: https://dart.dev/language/extension-types
  related_links:
    - text: "Primary constructors for classes"
      link: "https://dart.dev/language/constructors#primary-constructors"
      type: "external"
    - text: "Extension types constructors"
      link: "https://dart.dev/language/extension-types#constructors"
      type: "external"

Copy link

@eernstg eernstg Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'Dart 3.4' is not accurate, the new, generalized primary constructors feature hasn't yet been released, but it's being implemented and will definitely be released.

labels:
- "dart"
- "language"

- term: "Prop drilling"
short_description: |-
The process of passing data through multiple layers of widgets
Expand Down
Loading