How do you decide what order to put code in?

What order do you put classes and functions in within a file, when it doesn't affect syntactic or semantic correctness? What order do you put methods in within a class? If two "code paragraphs" don't depend on each other, which do you put first? Do you denote groupings of functionality with section header comments or whitespace?

Comments

[Ben Halpern]

Uncle Bob's clean code dictates that functions within a file should descend based on abstraction layers. So the high level stuff towards the top, and closer to the metal as you go lower in the file. This would mean I wouldn't put the function a function calls right underneath it unless there are no other public or high-level functions that deserve to be higher.

But that's just one take, I'm sure there are competing thoughts and I'd love to read them.

[Meghan (she/her)]

+1 that's the way that makes the most sense to me, though personally I do it backwards to that because imagining I'm the compiler, it makes more sense to put the functions that don't reference any other functions at the beginning, and then to build up down the file.

[Jason C. McDonald]

In the context of C and C++, at least, the distance between functions can be significant to performance.

If function A calls function B frequently, the two should be listed near each other in the code. That way, when things are compiled, the actual assembly instructions for function A and function B will be near each other (unless optimized otherwise by the complier toolchain).

That distance between functions is important for minimizing the effects of instruction cache misses, as a function call is a literal GOTO instruction (unless it's been inlined). The same is often true of member variables, by the way.

At least, that's what I'd always been taught, and my work in C++ seems to confirm it.

At the same time, I almost always group functions by their scope, putting public above protected and private in most cases. If I have no other factors at play, I'll also organize alphabetically. However, if one function makes heavy use of another, I'll try to shuffle things around to move them closer together. In especially performance-critical areas, I am not opposed to "breaking up" my scope groups to accomplish this.

But, again, if there's no such scenarios you need to worry about, go for practical and pretty - group by scope, organize alphabetically, constructors first, destructors last (within their scope).

[Valentin Baca]

for java classes, this is a rough outline, but it's not very strictly enforced.

public class Foobar {
    // public static final constants
    // private static final constants
    // private fields
    //
    // public static methods (usually means there are no constructors)
    //
    // constructors
    //
    // public methodAA
    // private methodXX that *only* methodAA calls
    //
    // public methodBB
    // private methodYY that *only* methodBB calls
    //
    // (and so on...)
    //
    // private static methods (usually validation)
    //
    // private methods used by several methods
}

public methods should probably be in alphabetical order, but not important at all.

I personally really dislike "section header" comments, since they do very little. I can tell where the private methods are because they say private. I really dislike seeing:

/**************PRIVATE METHODS**********************/

Two line breaks between "sections" is more than enough to indicate a new "code paragraph"

[rhymes]

I don't use OOP much these days and I think also this depends a lot on the framework and language you're using.

For example in Python everything is public so you tend to, if using classes, to write the main methods up in the class (the entry points) and the "private" part at the bottom. The "constructor" should be the first method also. The usual convention is to prepend an underscore to private methods or variables so that people will know it's not part of the interface. This way if you read a Python class top to bottom you can read the first few methods and find what is about.

Though if you adhere to the single responsibility principle your class should have only one main function :D

Grouping wise in a file the only criteria I have is if B needs A, A is listed before B which actually now that i'm writing it down is the opposite of what I just said I do for methods in a class.

Well, I have no criteria then :D