The Stepdown Rule

It has recently occurred to me that some people are ordering the functions in a class randomly, mostly based on gut feelings. It’s a good indicator that we should rehash the old, simple but very important….

Stepdown Rule

The rule tells us that the code in our class should be readable from top to bottom, descending one level of abstraction per function. It implies that the function ordering is no longer random. A caller function should always reside above the callee function.

Bad – Wrong Order

As you can see, organizing the code randomly makes it far harder to comprehend. Also, you might not be interested in comprehending the details at all, you could just want to get the idea on how the breakfast is done and the bad organization just caused you to read a lot of stuff that you didn’t want to.

Bad – Mixed Levels of Abstraction

It’s also important to extract the methods so that they keep the same level of abstraction. Even if the makeBreakfast method is not too long at this point, it’s still relatively hard to read.

To make a breakfast, you need to:

  • Add eggs
  • Cook them
  • Give your wife 20 percent of frying pan contents
  • Give yourself 80 percent of frying pan contents

Doesn’t that sound ridiculous?

Good

Top-to-bottom, the same level of abstraction per function, one level of abstraction down per function call – as simple as that!

What if…

  • … the lower-level function is used by two or more higher-level functions? Then place it below the last usage.
  • … there are two similar functions in the class? That’s actually a common temptation. As programmers, we’re organized minds, we like symmetry and all that stuff. Wouldn’t it look good if we did something like this:
    No. People rarely read or search the code by method similarity. Stay top-to-bottom:
  • … I’m writing a test, not a production class? Yet another common temptation. We often have some “factory” methods to prepare our test data and they might not be necessary to comprehend the test itself:
    This one’s tricky, but I’d stick to the stepdown (top-to-bottom) approach. I believe that in a majority of cases we feel tempted to push such stuff bottom because we’re too lazy to make the code right. If the test setup takes too much work and makes the test incomprehensible, maybe it means that we should improve the design or use some patterns, instead of “put it down and forget”?

Summary

The Stepdown Rule tells us that we should organize our code so that we can read the code top-to-bottom and each function call descends by one level of abstraction. It applies even if a function is used multiple times, there are similar functions in the same class or we’re writing unit tests. Last but not least, whether you choose to use the rule or not, remember to stay consistent! If I understand the key you use to organize functions in classes once, I should be able to use that understanding in any place in the project.

About the Author Grzegorz Ziemoński

King of Tidy Java, nerd that thinks about producing perfect software all the time and proud owner of 2 cats.

follow me on:
  • Michał Kuliński

    Great post. Very informative and easy to understand​.