style guide on method ordering
Rex Mottram
my code. But one area I've never seen any guidelines or best practices
is with regard to the ordering of methods within a class. This may not
seem like a big deal but I often waste time looking for, say, the
compareTo method of a subsidiary class while debugging an ordering
problem, and in general I'd like all my classes to conform to a
reasonable standard.
Take for instance accessor methods: you could have a policy of
clustering all setters together and all getters together. Or you could
place the setter and getter for a given attribute together. On this,
since I use Eclipse and it does the latter for autogenerated accessors,
I tend to follow its lead.
But even beyond accessors, there are questions wrt static methods,
constructors, toString(), etc. I've been tending toward something like
<static constants>
<static methods>
<private instance data>
<constructors>
<accessors>
<utility methods>
<standard interface methods>
<toString and friends>
where "<standard interface methods>" means methods like equals,
hashCode, and compareTo which I always place consecutively, and
"<utility methods>" simply refers to those which are in none of the
other sets. The private instance data and accessors are sub-sorted
alphabetically and the constructors are in order of number-of-parameters
such that "this(...)" tends to refer to the constructor immediately above.
Does anyone have bones to pick with the above, or value to add? Or can
point to widely-accepted style guidance?
Thanks,
RM
PS I'm sure the point could be made that if you're having trouble
finding methods it may be a sign that you should refactor into smaller
classes. And there might be something to that, but I'd still like to
have a good convention.
Rex Mottram
> There is no general means to subdivided methods of classes
> into categories, because the is no general internal structure
> of classes.
This is true, but in a value-free kind of way. Every class has a set of
static methods, of instance variables, of constructors, etc. Those sets
may be empty but they can still be discussed. I see nothing wrong with a
convention saying "IF you have static methods, it's a good idea to place
them at such-and-such a place".
For instance, in C code it's a common pattern to place static functions
above their callers so they don't need a separate declaration. We can
formulate that pattern even in the knowledge that much C code will not
have static functions.
For a Java instance: not all classes will override equals and hashCode,
but would anyone argue that it's not a good idea to place them next to
each other when they do exist, both because their semantics are
intricately bound and to make it obvious to a maintainer that they are
both overridden, as they must be?
> »methods should be grouped by functionality rather than by
> scope or accessibility. For example, a private class
> method can be in between two public instance methods.
> The goal is to make reading and understanding the code easier.«
>
> http://java.sun.com/docs/codeconv/html/CodeConventions.doc2.html
Thank you for the reference, though it addresses this specific issue
only tangentially.
RM
Tom Anderson
> But even beyond accessors, there are questions wrt static methods,
> constructors, toString(), etc. I've been tending toward something like
>
> <static constants>
> <static methods>
> <private instance data>
> <constructors>
> <accessors>
> <utility methods>
> <standard interface methods>
> <toString and friends>
I do exactly the same.
I sometimes group 'utility methods' with accessors for related properties.
If a Mortgage object has a balance and a payment rate, with getters, and a
method to calculate how long it'll take to pay it off completely, i'll put
them all together, rather than having the calculation method come later,
after getters for unrelated properties like customer, house details, etc.
> Does anyone have bones to pick with the above, or value to add? Or can
> point to widely-accepted style guidance?
Nope!
tom
--
It's the 21st century, man - we rue _minutes_. -- Benjamin Rosenbaum
Lord Zoltar
>
> Does anyone have bones to pick with the above, or value to add? Or can
> point to widely-accepted style guidance?
>
> Thanks,
> RM
>
> PS I'm sure the point could be made that if you're having trouble
> finding methods it may be a sign that you should refactor into smaller
> classes. And there might be something to that, but I'd still like to
> have a good convention.
Any convention is probably good enough, as long as it is documented
and followed. I've seen similar to what you're doing.
For Java, you might be able to get the IDE to help you: Some IDEs have
a method and member summary list that can be sorted, and the usually
have different icons to identify different types and scope. You might
also be able to find plugins for your IDE that do this in different
ways, or write your own if you have the resources to do so (or even
write a plugin that will automatically clean a file for you, to
conform to whatever template you decide - although a simple script
could probably also be added to do this and invoked by your build
process as a precompile step...) ;)
somewhat off-topic:
C# has the ability to define "regions" of code which (as far as I can
tell) are only used by the editor to help you group methods or
members.
You can also define classes as "partial", which means that one class
can span multiple files. For example, you could have a file for public
methods, another for private, another just for getters/setters, etc...
but I think that much decomposition would be overkill (Visual Studio
does this automatically to split forms up into two classes: one for
the UI setup work, and one for all the code you write for the form).
You might be able to do this in Java too, by using private classes in
a package, and exposing one public class that references the others. I
can't see a purpose for that, but maybe someone else can...
Mark Space
> But even beyond accessors, there are questions wrt static methods,
> constructors, toString(), etc. I've been tending toward something like
>
> <static constants>
> <static methods>
> <private instance data>
> <constructors>
> <accessors>
> <utility methods>
> <standard interface methods>
> <toString and friends>
>
It all depends. I always try to put "main" first, if present. Top down
is a good thing, even today.
Private instance fields is a tough call. I like to put my constructors
first, if possible, but many folks are used to seeing variable
definitions up top. It's a judgment call.
Ditto with static final constants. If the final variable is only used
with some methods, it might go next to them. Otherwise, it's a
candidate for being up top, just because many people expect it there.
Note that some auto-code generators put generated private fields last.
This is against code guidelines, but it works. They're generated
fields, you don't really want to be bothered by them, so they go at the
end of the class definition.
Static methods by default go last for me, not first. But it's better to
group them with similar function. A static "newInstance" method goes
with the constructors.
Don't be afraid to break all the rules if it makes a given class
definition more clear.