4

Let's say I have a basic procedural program which is well structured into decomposed functions. For example, a main() function which calls functions a and b, which in turn each call functions c and d, and e and f. In pseudo-Python, this could be written bottom-up like this:

def c():
    # Do stuff

def d():
    # Do stuff

def e():
    # Do stuff

def f():
    # Do stuff

def a():
    c()
    d()

def b():
    e()
    f()

if __name__ == "__main__":
    a()
    b()

However, it could also be written top-down like this:

if __name__ == "__main__":
    a()
    b()

def a():
    c()
    d()

def b():
    e()
    f()

def c():
    # Do stuff

def d():
    # Do stuff

def e():
    # Do stuff

def f():
    # Do stuff

In general, in many languages, both of these would be valid, but is there a preferred coding style? I'm primarily thinking of readability/maintainability here, not efficiency of compilation or execution. Does it vary between languages? I'm thinking firstly of Python here, but there are many other languages this question could apply to here, so I'm happy to make it broader.

Note: I am not thinking about the design of the program here (whether to think top-down or bottom-up first), I am specifically talking about the ordering of the source code.

Community
  • 1
Andrew Ferrier
  • 157
  • 8
  • 2
    In some languages( e.g. pascal ) the second form isn't valid - the functions must be defined lexically before they are used – Caleth May 10 '16 at 12:32
  • 1
    I've never seen the `__main__` block at the top of a Python module. – Jace Browning May 10 '16 at 12:38
  • 1
    I see this has been put on hold as opinion-based. I've tried to tweak the wording here a little; I'm looking for comments based on established standards or conventions, not just personal opinions. – Andrew Ferrier May 10 '16 at 12:40
  • You touch a longstanding mystery of programming. In 30 years of coding, I have never yet discovered a single answer to it. What I have discovered is this: Program design tends to be an iterative process. Often, you start with a vague idea of overall design, then begin by working on one of the modules, *then* return to refine the overall design, and so on. Often, the overall design (as it eventually emerges) is somewhat constrained by the desire not to redo modular work already completed. In short, it may be than no answer to your interesting question in principle exists. – thb May 10 '16 at 13:35
  • A program written top-down is easier to understand if you're reading it for the first time. Think of an article where the author introduces the main points, then explains each point. On the other hand, a newspaper article is written with the most important information first. What would "the most important information" of a program be? – Gilbert Le Blanc May 10 '16 at 17:07

2 Answers2

3

Not much of coding in Python and its long time since I coded in C.

For C programs, I used to prefer top-down, because that is how I design my programs. If a calls b, b is listed after a. I also used to have a header for each .c file that lists all functions in it and included in the .c file.

I follow the same model in Java class methods now.

Dakshinamurthy Karra
  • 141
  • 4
-2

The point of writing a method is to do one thing in an obviously correct way. This principle is usually applied to explain why over-long methods are bad; a method should fit on your monitor in one piece.

But it also cuts the other way: a method should not be so small that several fit on your monitor at the same time! This means that it is quite irrelevant in which order they appear in the source. As long as your language does not require declaration-before-use, and you have a decent environmant that lets you jump from use to definition at a single keypress, there is simply no reason to care one way or the other. I'd go further and say: if you care which way your methods are ordered, then they are doing too little.

Kilian Foth
  • 107,706
  • 45
  • 295
  • 310
  • 6
    -1, there is IMHO nothing wrong in having lots of small methods. There can be "too many layers of abstraction" in code, but that is nothing one measures by the method size. – Doc Brown May 10 '16 at 11:53
  • I tend to favor Bob's recommendation of having one to a few lines per method/function. I try to make each method look like almost natural language describing what the method does, given the current abstraction level. This goes well hand in hand with SRP since you shouldn't need more than a few words to describe what most methods do. – sara May 10 '16 at 12:18
  • @DocBrown agreed. I think there are many valid cases where several methods can fit on the same screen at once. I tend to find the opposite; methods over a screen in length are a good smell that refactoring *might* be needed. It all depends what you're writing. – Andrew Ferrier May 10 '16 at 12:38
  • I won't down vote because I simply disagree with your answer, but it is a valid answer, so it doesn't deserve a down vote IMO. I tend to care about the order because I like the main methods near the top so I can quickly see the key functionality provided by the class. The stuff near the bottom should just be helper/utility/private methods or even unimportant to the main point of the class methods. With that said, I am not a zealot about following this philosophy because like you said, it doesn't matter all that much. Now tabs versus spaces, that matters:) – Dunk May 10 '16 at 19:00