1

I am working on a coding convention to follow for my Java projects. I find it easier to find my way through a class when I group its methods by category. For example, rather than having each getter/setter pair for a variable one after another in a long list, I find it easier to group all the getters in a section, and all the setters in another. This means my code is organized like this:

public class MyClass {
    //=========================== Instance Fields ============================//

    //========================== Instance Interface ==========================//
    //----------------------------- Constructors -----------------------------//

    //------------------------------- Getters --------------------------------//

    //------------------------------- Setters --------------------------------//

    /* More categories? */

    //============================ Static Fields =============================//

    //=========================== Static Interface ===========================//

}

The problem with this approach is one with my knowledge: I do not know how to categorize every method. Obviously, I am familiar with constructors, destructors, getters, and setters. I have also heard of observers/queries, transformers/mutators, and iterators, though I have not yet found standardized names for these. But then there are methods that leave me scratching my head, like methods for immutable classes that return a new version of that object that represents a change to that immutable state.

Is there a standardized set of categories in OOP that cover what methods can do? If so, could someone provide a list of these names and explanations for what that category does? If these categories are language-specific, could you also provide a Java-specific set?

closed as too broad by Philipp, Tulains Córdova, JeffO, GlenH7, gnat Mar 24 '15 at 6:40

Please edit the question to limit it to a specific problem with enough detail to identify an adequate answer. Avoid asking multiple distinct questions at once. See the How to Ask page for help clarifying this question. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 1
    You can group methods by modifier type also: public, package, protected, private. However, I don't do it like this. I rather group methods by functional coherence in such a way that methods which are build on one another are in close proximity in the file. I know, with modern IDEs you don't really need that feature, but I like it more than grouping by technical categories. – Falcon Mar 23 '15 at 13:36
  • 1
    What are instance interfaces? – Tulains Córdova Mar 23 '15 at 13:38
  • @Falcon: I know about the approach you call "functional coherence", since that is the approach Robert Martin advocates in Clean Code. However, I dislike this approach since it does not work well with DRY and designing small methods that perform a single function. Where do you put a validation method that many of your public methods need to call? That said, I do agree with Martin in that a file should be well-organized by some understandable logical order. Relying on IDEs and allowing code to become very disorganized makes it impossible to review code easily in other mediums. – sadakatsu Mar 23 '15 at 14:30
  • @user61852: This is an unfortunate collision between OO terminology and Java terminology, but I do not know what else to call it. In OO, an interface is the set of methods that a type exposes (and, recursively, a type is defined by the methods it exposes as its interface). In Java, an interface is a coding mechanism used to impose the OO concept of a type. They are related but different. When I say "instance interface", I am talking about the methods a class exposes to interact with instances of its objects. Similarly, a "static interface" are the methods the class exposes statically. – sadakatsu Mar 23 '15 at 14:33
  • Shouldn't it then be public dynamic methods and public static methods? The names you use are sui generis. – Tulains Córdova Mar 23 '15 at 17:36
6

I don't agree that you should be sorting your methods by category, or even by visibility. It may seem, at first, like this is a good thing to do, but what you're actually doing is imposing order for the sake of order, but not for any particular reason. Consider ensuring that your address book were sorted by phone number. Certainly, it would be organized, but your organization scheme would not be very useful. What are you trying to minimize with your address book? Answer: the amount of time it takes you to look up an address. Keep this in mind towards the end of my answer.

What, then, should the organization scheme be?

From Clean Code:

Have you ever chased your tail through a class, hopping from one function to the next, scrolling up and down the source file, trying to divide how the functions relate and operate, only to get lost in a rat's nest of confusion? Have you ever hunted up the chain of inheritance for the definition of a variable or function? This is frustrating because you are trying to understand what the system does, but you are spending your time and mental energy on trying to locate and remember where the pieces are.

Concepts that are closely related should be kept vertically close to each other. Clearly this rule doesn't work for concepts that belong in separate files. But then closely related concepts should not be separated into different files unless you have a very good reason. Indeed, this is one of the reasons that protected variables should be avoided.

You should read the entire chapter, it goes on at some length about this. I could put it all here but I don't want to violate Robert Martin's copy right too much. But, basically, the next part says this:

  1. Local variable declarations should be as close to their usage as possible.
  2. Keep your instance variables (fields) at the top, as you're already doing.
  3. Put dependent functions after the functions that call them.

#3 is the key organization concept. You want to read your code like you would read a newspaper article. Each public method should have it's private dependencies immediately following, with good variable names. Remember that address book. The goal is to minimize the amount of time you spend scrolling up and down your classes to find relevant behavior, so that your mind can focus on the "what the system does" as you continue to program.

  • I have read this chapter of Clean Code. As I said to Falcon above, I disagree with Martin on this approach because I find his rule for building small methods that perform specific purposes far more important than clustering methods visually by call chain. For example, many methods need to validate their arguments, so put that repeated validation in a method. Which of the many methods that call the validation method do you put the validation method next to? My whole motivation is imposing a logical structure to increase search speed and makes it easier to understand a class. – sadakatsu Mar 23 '15 at 14:45
  • 3
    @sadakatsu Yes but you're attempting to create an organizational structure that is not intuitive in real time and doesn't yet exist. You're overthinking this. – durron597 Mar 23 '15 at 14:51
5

Is there a standardized set of categories in OOP that cover what methods can do?

No, since by definition, methods can do anything. But you're solving a symptom.

I find it easier to find my way through a class when I group its methods by category.

This is a sign that your classes are too big, and/or doing too much. It also might be a sign that you're not using your IDE as efficiently as you could be.

Java makes this difficult, especially if you're javadoc-ing everything but you shouldn't need this level of organization to navigate in your class. IDEs provide go to source/declaration. They provide class summaries to help navigation. And if your class is properly only dealing with one responsibility, it should only take up a few screens at most anyways.

Having fields, constructors, properties and methods in groups helps the readability of the code. Grouping methods by visibility can sometimes help, sometimes not. Doing more is probably overkill. Needing more is a sign that something has gone wrong.

  • -1 (if I could, but my reputation does not allow). You assume that my question is irrelevant because you believe that my need is irrelevant based upon the assumption of poor practices. I find it easier to think about classes if I can break down their internal structure categorically. Source files are easier to read if they are organized visually. Furthermore, IDE features for finding methods or fields by name makes it easy to get lost in a train of thought. Imposing a visual ordering on the class that enables encapsulation by categorization makes thinking about my code easier. – sadakatsu Mar 23 '15 at 14:21
  • @sadakatsu - That's all well and good, but (unless you're a dramatic statistical outlier) you will very rarely be writing code by yourself. You will not be able to impose such a rigid visual ordering on your classes when on a team - especially when other team members are very likely to categorize their methods different than you would. – Telastyn Mar 23 '15 at 14:29
  • I understand this. Unless I am the lead programmer, I could not enforce such a standard. But I said that this was for "my" Java projects. I am specifically talking about projects in which I am coding alone. Besides, I provided my motivation to help explain what I meant by "method categories", since I feared that might be vague. I might need to edit the question, but I think that knowing correct terminology to describe methods is helpful in its own right, regardless of my nefarious purposes. – sadakatsu Mar 23 '15 at 14:40
  • @sadakatsu One problem is that there're no really useful categories. As already said, separating getters from setters is no good idea, but at the same time, separating modifying methods from non-modifying might be. Othertimes, separating by visibility may be more important. I spent quite some time thinking about it and just gave up. I try to organize methods by call chain, but I try only very lightly as the gain is pretty limited. Moving methods around to conform better to any rules is a terrible idea because of VCS, so I just don't care. By using project Lombok I can keep classes very small.. – maaartinus Apr 6 '15 at 2:54

Not the answer you're looking for? Browse other questions tagged or ask your own question.