Class Content Order
There is nothing special about class content order as compared to the ordering of anything else in your life. As Benjamin Franklin said, “A place for everything, everything in its place.“ Whether it’s your kitchen, your garden, or your class file, order optimizes for one or more functions.
Keep in mind that it’s “A place for everything” and not “A place for everything for everyone”. Continuing the kitchen metaphor, someone that cooks often and for multiple people will order their kitchen to optimize for cooking. Perhaps they will hang their cookware from a rack and their oven and stove will be prominent; they may not even have a microwave. Whereas someone that cooks infrequently and for themselves will order their kitchen to optimize for quick meals. Perhaps they will have a one-pot cooker, an induction heating plate, and a microwave. The point is that order depends on the function you are optimizing for.
Class Content Function
So what is the predominant function of class content? After source implementation, I would say the predominant function of class content is to impart to the reader full knowledge of what the class does. So then class content is responsible for:
- Implementing the class attributes and behavior
- Supporting the reader to understand what the class does
- Supporting the writer to change class content with minimal impedance
Class Content Order
If we’re in the ballpark of what the predominant functions of class content are - then how do we optimize for those functions? What patterns and practices do we follow to optimize for those functions? Let’s unpack each function one by one.
Implementation of Class
This one is super easy. The compiler does not care a whit about class content order, or handling of indentation, line breaks, etc. Thus there is nothing to optimize other than write good code and cover that code fully with tests.
Support Reader Comprehension
This is where the most optimization is available to us. Consistent indentation so that the reader does not need to do any gymnastics figuring out begin/end blocks. Similarly, line breaks may be used to support the reader to see full argument lists as well as see method calls in one glance. Naming plays a huge role in comprehension: choosing adequately descriptive names supports the reader to quickly understand what a variable, parameter, or member is for.
What about order? How can the order of class content be optimized for reader comprehension? Make it easy for the reader to find class content. The first thing we can do in terms of order is to group class content in a logical manner. You’ve likely seen some version of that, such as: data, static, public, protected, private, nested. These are very natural groupings and represent partitions of purpose within the class content. You may use another grouping scheme, but the point is the first optimization of order is to group in a logical manner.
The next optimization of order is what we generally mean when we talk about class content order. Within a group, where should method A be relative to method B? There are two schools of thought here: Dependence Order and Alphabetical Order. Let’s look at the pros and cons of each.
Dependence Order
When methods are organized to reflect who uses what, that is what I am calling Dependence Order. The idea is that if A calls B then B is located in class content directly after A. The optimization goal is that a reader will read A and then be able to glance (or scroll) down and see the definition of B, thus continuing the “story” without interruption. That is the main pro for using Dependence Order.
But what if C also calls B? Where to put B then - after C or after A? And what if A also calls X, Y, and Z? Do those go before or after B? If A no longer calls B then do we move B somewhere? Where to? And doesn’t that add distraction/noise to the PR? What about when a writer makes a change to the class content and gets the Dependence Order wrong? Now what happens to the consistency of our “story”? How do we instruct the editor to reorder class content for Dependence Order? Editors generally cannot do that. These are but a few of the pressures that exist when using Dependence Order.
Alphabetical Order
As you can see, the consistency of class content can easily break down when using Dependence Order. And as we established early on, the absolute worst order is disorder. If the class content falls into disorder, then the reader does not have enough guiding the reading process - so we must avoid that at all costs. Enter Alphabetical Order.
When methods are organized alphabetically, we call that - yup you guessed it - Alphabetical Order. Thus within a grouping, method A is located in class content directly before method B. Generally editors support reorganizing class content by alphabetical order. Thus at all times class content is ordered consistently. As a reader I know if I see A call B, then I just scroll down to find B (or use method navigation provided by the editor). If a writer makes a change to the class content and gets Alphabetical Order wrong, then a simple reorder of the class content restores consistency of order.
I trust you see that Alphabetical Order is more sustainable than Dependency Order, and thus we must commit to it - otherwise we are accepting the future disorder of our class content.
Conclusion
I started this post off with an example of order preference (caterer vs. solo diner). I think about this when I think about someone having a preference for Dependence Order. They are attempting to optimize for a function - but they are like the solo diner in that the order makes sense to them in the moment. Once you expand out to multiple readers and writers, the only class content order I have found that works is Alphabetical Order.
That said, if you have developed a sustainable solution that differs I would love to hear about it.