I generally try to stay as close as possible to standard Java style in 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
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.
Stefan Ram wrote: > 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.«
On Fri, 16 May 2008, Rex Mottram wrote: > But even beyond accessors, there are questions wrt static methods, > constructors, toString(), etc. I've been tending toward something like
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
> 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...
Rex Mottram wrote: > But even beyond accessors, there are questions wrt static methods, > constructors, toString(), etc. I've been tending toward something like
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.
