CodeStyle Convention - Ordering

[DanVanAtta]

Following up on: https://github.com/triplea-game/triplea/pull/3205#discussion_r172066196 with @ssoloff

So, should devs be using the static-first declaration order going forward? Since we can't enforce it, should it at least be in the dev docs? How should it play with the existing convention to use depth-first ordering (e.g. an instance method that calls a static method that is otherwise unused anywhere else)?

Good set of questions. We have not actually formalized all of these points beyond 'depth first ordering'.

We have agreed that our first precedent will be google java code style, second would be the default java community (oracle) standards.

Here is what google has to say:

3.4.2 Ordering of class contents The order you choose for the members and initializers of your class can have a great effect on learnability. However, there's no single correct recipe for how to do it; different classes may order their contents in different ways.

What is important is that each class uses some logical order, which its maintainer could explain if asked. For example, new methods are not just habitually added to the end of the class, as that would yield "chronological by date added" ordering, which is not a logical ordering.

3.4.2.1 Overloads: never split When a class has multiple constructors, or multiple methods with the same name, these appear sequentially, with no other code in between (not even private members).

https://google.github.io/styleguide/javaguide.html#s3.4.2-ordering-class-contents

---

That does not give us a lot of guidance. AFAIK the java community convention is:

• variables first
• higher scopes, statics, final raises ordering in that priority ordering. So public static is before public final, but private static is after public final.
• public static methods, and any private static methods they call
• constructor followed by any methods it calls in depth first ordering
• any further instance methods, with anything they call in turn by depth-first ordering.

The ordering of methods within a class are to some extent determined by the class itself. Whether a public static method is considered part of a depth-first ordering or a proper public static is up to the author (but such examples probably indicate an abstraction problem).

[DanVanAtta]

@ssoloff should we pursue this? does the above make sense? There is no hard rule of 'statics' first, as 'private static' are helper methods and can be found next to public methods. Idea is for best cohesion, though I'm not 100% sure why statics methods go above constructor :man_shrugging:

Please re-open if you'd like to see about adding some checkstyle rules or to discuss further.

[ssoloff]

though I'm not 100% sure why statics methods go above constructor

Right, that's why I brought this up in the first place. That's atypical in the Java codebases I've looked at.

I was simply suggesting we enforce member ordering via Checkstyle so we don't have a potpourri of styles. Unfortunately, Checkstyle only supports one member ordering style (Oracle's), so if we don't want to use that, then, yeah, there's really nothing else to discuss here.