Everything old is new again. The folks who brought us the eXtreme Programming books were, among other things, promoting a set of best practices in software development. One of them, which they termed “Programming by Intention”, was not actually new, but was something that had been a very common coding technique in languages like COBOL and Smalltalk (usually called “top down” programming) years before.

(from the introduction of Programming by Intention)

Programming by Intention appears to be a rediscovery of top down programming where one starts with the top layer and goes down from there.

This was the way that code was written in the days of Pascal and its contemporaries. You started writing the main procedure (it happened to be located at the end of the file, by necessities of the language definition and compiler) and then write a procedure or function, which was then located before the code that called it.

This contrasts with the ‘bottom up design’ model that OO emphasizes – building the building blocks first, and then building them up from there.

It would be a misconception and misapplication of Programming by Intention to use this to lay a structural framework to the code. Unless the language defines it (a la pascal), it doesn’t matter what order the methods are declared in. Readability (and consistency between programmers) is key.

With modern IDEs, one can see the outline of the code quickly and easily. Hitting F3 in eclipse will open up the definition of a method call no matter where it is located in the code. To this extent, the organization of the methods is unimportant. If there is an order use the following guideline:

1. Program within the language constraints.
2. Program within the language conventions.
3. Program within the team’s style constraints.
4. Program consistently.

If you order top down or bottom up or depth first or breath first or alphabetical, do it. And stick with it.

I don’t know if this is actually specified in programming by intention, but maybe we can analyse pros and cons.

In prolog, a 5th generation programming language, you can use both forms of execution, thus from a pseudocode point of view both could be valid.

Breadth-First has the advantage that it can be read in a top-down fashion, if your functions vary widely in abstraction with each level then it may be possible to skip one level. Breadth-first would be the way to go.

However, if someone reading this has to read everything, or to avoid making assumptions about that, then depth-first would be better. It allows reading the code in the same way it is executed and makes reading it more easy and natural, think about the example of alligator eggs 😉

The best option is to have some tool that allows to sort everything in a depth-first fashion and collapse inner elements. I’ve seen that in many code editors and in the html generated by FreeMind. That allows the reader to choose the direction to continue, either breadth-first by collapsing and scrolling or depth-first by expanding and scrolling.

In general, depth-first is a much safer option.

I follow Robert C. Martin’s Step-down Rule. In his book Clean Code, he writes:

We want the code to read like a top-down narrative. We want every function to be followed by those at the next level of abstraction so that we can read the program, descending one level of abstraction at a time as we read down the list of functions. I call this The Step-down Rule.

Reading the code means you descend one level of abstraction at a time. Per your example, the narrative when reading the code would be

1. To do O, we do V and E
2. To do V, we do R and F
3. To do E, we do L and W
4. Here are the low-level details of how R is done
5. Here are the low-level details of how F is done
6. Here are the low-level details of how L is done
7. Here are the low-level details of how W is done

If the reader wants to understand O, they may be able to stop reading after item 1, 2 or 3 above, depending on how many implementation details they want to know.