Patterns for declaring functions for greater readability

Question

In C++ functions needed to be declared before they were called. This could be worked around with function signatures but for the most part this is no longer required in newer programming languages, C#, Python, ETC.

However, while reading other peoples, code and when having to structure functions in a class, I find that I miss the consistency that existed in C++.

What patterns exist to declare/order function while maintaining readability and understanding about the structure of your code?

Edit 1

---

Here is an rough example.

class A
{
  private FunkB()
  {
    ...
  }

  private FunkC()
  {
    ...
  }

  public FunkA()
  {
    FunkB();
    FunkC();
  }

  public FunkD()
  {
    FunkC();
    ...
  }
}

v.s.

class A
{
  public FunkA()
  {
    FunkB();
    FunkC();
  }

  private FunkB()
  {
    ...
  }

  private FunkC()
  {
    ...
  }

  public FunkD()
  {
    FunkC();
    ...
  }
}

Edit 2

---

This would be a guideline for writing code regardless of editors. Newer editors have excellent "go to definition" features and book marks help out with this too. However I'm interested in a editor independent pattern.

Answer 1

In an IDE the order of the methods seems to matter much less to me. I don't read the whole source, rather I procede like this: read a method, spot an interesting function call, ask IDE to open declaration of that function (which may well be in a different source). Or find an interesting fucntion, wonder where it's used, ask the IDE to list the references.

The IDE usually displays a summary lisyt of the methids in a class, and sorts it and filters it in various ways, so once again the end-to-end read is not needed.

The one thing I do want is a "what's this class for" understanding. There's two things that help with that: Programming to Interfaces - and good class documentation.

So I would encourage clearly documented responsibilities for the class, often expressed in terms of specific Interfaces. The order of methods in the source is less important to me.

Answer 2

When reading the code of a method in isolation, you want to understand the intent of the method. If the level of abstraction inside the method is good, and the names of all other called methods make sense in its context, you won't need to know them in order to understand the code. You'll treat them like black boxes.

Some principles that help achieve greater readability in the small:

Single Level of Abstraction Principle

Single Resposibility Principle (pdf)

Composed Method

And don't forget, always use good names! That's why your example is not good for this discussion.

Answer 3

As previously mentioned, with any decent IDE the order of functions in the file becomes much less of an issue. This is also particularly the case with object-oriented languages, where other methods of navigation are more useful than sequential reading. For example: class heirarchy; class outline; call heirarchy. If you really miss the function definitions, maybe there's something in the language that would fit that purpose instead, e.g.: pure virtual classes in C++ (if that's what they're called) or interfaces in Java.

However, having said that, whenever I'm reorganising the text in a source file, I always tend towards ordering functions based on their cohesion[1]. After that I go in the order the functions were born. If, like your example, I have a function from which other, smaller helper functions were born, I would place them below where they were extracted from. I just find it more intuitive to read what's important first, and ignoring the smaller details until I need to know them, and seeing the larger method first generally accomplishes this. This would appear to be more like your second example.

To summarise, I'd go Big then Small, or Public then private helpers.

[1] This is a a code smell if there are too many groupings within one class/file, suggesting they should be split up into smaller, separate units.