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 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]

On Mon, Jul 27, 2015 at 9:44 AM, Mike Lewis <mikele...@gmail.com> wrote:

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 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

[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.

[Bob Nystrom]

On Mon, Jul 27, 2015 at 11:16 AM, Mike Lewis <mikele...@gmail.com> wrote:

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

[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)

[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]

On Mon, Jul 27, 2015 at 6:15 PM, Thomas Schranz <tho...@blossom.io> wrote:

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