Orchestrating inferiors

Some vague thoughts about clarity in code: I’m thinking that the code at each layer of abstraction should speak about the inferior layer – provide an introduction to what that layer is about. I have a feeling that you should perhaps let the superior layer orchestrate the inferior rather than encapsulate the sequences of invocations at the inferior layer.

I’ll try to give an example of this: say that the superior layer wants to do something that involves three objects, A, B, and C – which participate in sequence to do something (A does something which produces a result, which is fed into B, and so on). You could wrap this in a function at the same layer of abstraction as the three classes, but I have the feeling that it’s better to let the superior layer do it, in order to tell a better story about the inferior layer.

Clarity in code has to do with communicating intent. Just as you want to convey a clear message to your reader if you’re writing text, you want the reader of your code to, wherever he or she looks, get a bigger picture of what the code does – a sense of the immediate surroundings (surrounding meaning other code used by the code being inspected); suggestion. The code should lead the reader to expect things about the rest of the system – and those expectations should be proven true. I feel that you have a greater chance of doing that if you orchestrate inferiors – a lower-level function encapsulating the orchestration could do this if it’s well-named, but I wonder whether it would be as effective.