[dart-misc] Class organization, style guide, conventions, best practices

[Mike Lewis]

In building my API, I've found it difficult to come up with a consistently
nice way to organize the members within my classes. The Dart Style Guide
<https://www.dartlang.org/articles/style-guide/#members> only touches on
constructors, and simply recommends *using* things like setters and
getters. But is there a recommendation or best practice for how to lay out
a class that helps for readability and navigation? For example, should a
constructor always be at the top? Would it make more sense to put all
static members before or after instance members? Private before public? etc.

I could see this being difficult to standardize and may just depend on
subjective preference or the target application of an API, so I'd also be
interested in a recommendation for an existing library package (one where
the classes are very nicely laid out) to use as a model.

['Bob Nystrom' via Dart Misc]

Post by Mike Lewis
In building my API, I've found it difficult to come up with a consistently
nice way to organize the members within my classes. The Dart Style Guide
<https://www.dartlang.org/articles/style-guide/#members> only touches on
constructors, and simply recommends *using* things like setters and
getters. But is there a recommendation or best practice for how to lay out
a class that helps for readability and navigation? For example, should a
constructor always be at the top? Would it make more sense to put all
static members before or after instance members? Private before public? etc.
I could see this being difficult to standardize and may just depend on
subjective preference or the target application of an API, so I'd also be
interested in a recommendation for an existing library package (one where
the classes are very nicely laid out) to use as a model.

We have discussed having style guidelines for this. It gets pretty complex
when you consider all possible combinations of:

- Public/private/protected-like
- Override/abstract/normal
-
Method/getter/setter/operator/constructor/factory/field/variable/function/class/typedef
- Static/instance

We could specify a global ordering of all of those, but there are often
special cases where it would make sense to ignore that. For example, it
often makes sense to keep a public getter next to the private field it
returns. But when multiple getters are backed by the same state, the field
may end up elsewhere.

Personally, my very rough guidelines are:

- Put state (variables and fields) near the top. State is one of the
most important things you need to reason about to understand OOP code, so I
try to make it obvious by putting it near the beginning of the file.

- Public stuff before private stuff. A library is used more often than
it's modified, so this puts the public API, which more users will need to
see, near the top.

- Static or top level stuff before instance stuff. Since you have to go
through a constructor to get to instance stuff, I think of it is slightly
less accessible.

- Members are ordered roughly fields/getters/setters, constructors,
operators, methods. Sometimes I swap the first two.

- Overrides generally go after new members.

- Methods go after things that call them.

Note that these often conflict with each other, which is a big part of why
we don't have precise guidelines. :)

Also, in practice, I don't think it matters much. People rarely read source
files top to bottom and rely on search and navigation. Source files are
getting closer to unstructured bags of code every day.

Cheers!

- bob

[Thomas Schranz]

I love these. Great tips for any language imho.
I'd like to see something like that in a style guide
since a lot of people are writing OOP code and these rules of thumb are
great & concise.

(but I understand that it might get too long etc)

Post by 'Bob Nystrom' via Dart Misc

Post by Mike Lewis
In building my API, I've found it difficult to come up with a
consistently nice way to organize the members within my classes. The Dart
Style Guide <https://www.dartlang.org/articles/style-guide/#members> only
touches on constructors, and simply recommends *using* things like
setters and getters. But is there a recommendation or best practice for how
to lay out a class that helps for readability and navigation? For example,
should a constructor always be at the top? Would it make more sense to put
all static members before or after instance members? Private before public?
etc.
I could see this being difficult to standardize and may just depend on
subjective preference or the target application of an API, so I'd also be
interested in a recommendation for an existing library package (one where
the classes are very nicely laid out) to use as a model.

We have discussed having style guidelines for this. It gets pretty complex
- Public/private/protected-like
- Override/abstract/normal
-
Method/getter/setter/operator/constructor/factory/field/variable/function/class/typedef
- Static/instance
We could specify a global ordering of all of those, but there are often
special cases where it would make sense to ignore that. For example, it
often makes sense to keep a public getter next to the private field it
returns. But when multiple getters are backed by the same state, the field
may end up elsewhere.
- Put state (variables and fields) near the top. State is one of the
most important things you need to reason about to understand OOP code, so I
try to make it obvious by putting it near the beginning of the file.
- Public stuff before private stuff. A library is used more often than
it's modified, so this puts the public API, which more users will need to
see, near the top.
- Static or top level stuff before instance stuff. Since you have to
go through a constructor to get to instance stuff, I think of it is
slightly less accessible.
- Members are ordered roughly fields/getters/setters, constructors,
operators, methods. Sometimes I swap the first two.
- Overrides generally go after new members.
- Methods go after things that call them.
Note that these often conflict with each other, which is a big part of why
we don't have precise guidelines. :)
Also, in practice, I don't think it matters much. People rarely read
source files top to bottom and rely on search and navigation. Source files
are getting closer to unstructured bags of code every day.
Cheers!
- bob

[Kasper Peulen]

Great tips indeed, maybe not something for in the style guide, but more
like something where a blog post could be about ?

['Bob Nystrom' via Dart Misc]

Post by Thomas Schranz
Great tips for any language imho.

Full disclosure: When I was a game programmer at EA, I wrote the C# style
guide we used at my studio. These are basically the same rules I had there.
:)

- bob

[Mike Lewis]

Thanks, Bob. I'll take what I can get :)

But FWIW, I interpret the Style Guide as something that can be partially or
entirely ignored anyway, so it might still be useful to have at least some
of what you just mentioned in there.

Post by Mike Lewis
In building my API, I've found it difficult to come up with a consistently
nice way to organize the members within my classes. The Dart Style Guide
<https://www.dartlang.org/articles/style-guide/#members> only touches on
constructors, and simply recommends *using* things like setters and
getters. But is there a recommendation or best practice for how to lay out
a class that helps for readability and navigation? For example, should a
constructor always be at the top? Would it make more sense to put all
static members before or after instance members? Private before public? etc.
I could see this being difficult to standardize and may just depend on
subjective preference or the target application of an API, so I'd also be
interested in a recommendation for an existing library package (one where
the classes are very nicely laid out) to use as a model.

['Bob Nystrom' via Dart Misc]

Post by Mike Lewis
But FWIW, I interpret the Style Guide as something that can be partially
or entirely ignored anyway, so it might still be useful to have at least
some of what you just mentioned in there.

Sure, and in fact the guidelines themselves are weighted in terms of how
stringently we think people should follow them (or, conversely, how likely
we think it is that you're run into a reasonable exception to the rule).

But there is also a brevity goal. A style guide that is too long will turn
off readers completely leading to them ignoring *all* of it. So we try to
only add rules that we really think add value, or can be expressed
concisely.

Cheers!

- bob