Headlines Technique

Also, if one makes comments stand-out well, then a function can read like a newspaper where the headlines stand out:

    // ---- Wake Up ----
    .
    foo = bar + adsfsdf()
    blah go ga do dad
    zarg(aasdf, sddfsdf, sdf, asdf, asdf)
    .    
    // ---- Shower ----
    .    
    if (asdfsdf() > sfssdf) {
      foo = bar + adsfsdf()
      blah go ga do dad
      zarg(aasdf, sddfsdf, sdf, asdf, asdf)
    }
    .    
    // ---- Shave ----
    .    
    foo = bar + adsfsdf()
    blah go ga do dad
    zarg(aasdf, sddfsdf, sdf, asdf, asdf)
    .    
    // ---- Get Dressed ----
    .
    ...etc...

    (Dots added to avoid a known wiki bug that affects many non-MS browsers.)

Allegedly better written as

    void GoToWork?(){  //look ma, no complex conditionals
      WakeUp?();
      Shower();
      Shave();
    }
    void WakeUp?(){
      foo = bar + adsfsdf()
      blah go ga do dad
      zarg(aasdf, sddfsdf, sdf, asdf, asdf)
    }
    void Shower(){
      if(asdfsdf() <= sfssdf)return; //complex conditionals are much better as guard clauses to methods
      foo = bar + adsfsdf()
      blah go ga do dad
      zarg(aasdf, sddfsdf, sdf, asdf, asdf)
    }
    void Shave(){
      foo = bar + adsfsdf()
      blah go ga do dad
      zarg(aasdf, sddfsdf, sdf, asdf, asdf)
    }

Discussion:

I think the second is a bit misleading because unless one is using something like Pascal, there are possibly, perhaps probably, a bunch of parameters to manage, which adds to complexity.

What makes a method name any better than a comment in the style presented? You can see everything you need to see and you can drill down on what you want without having to go search the file. The higher level logic is perfectly observable.

Because a method name is compiler enforced(language dependent), and reusable from other contexts, the comments don't do anything. Use the language, that's what it's there for. When I have to later write GoToParkAndPlay?, I'll be able to call

    WakeUp();
    Shower();
    Shave();
    GetDressed();
    LeaveHouse();

and reuse them, you'll have to write another huge function, or worse, you'll cut and paste it into the new function and duplicate it all.

Reuse is a different issue. What happened to DoTheSimplestThingThatCouldPossiblyWork? Adding another method is not the simplest thing. When you need to reuse it, then you can extract it out. (Domain-specific functions have a low rate of reuse anyhow in my experience.) Doing it first means BigDesignUpFront which I hear is bad. I don't get the compiler method name angle. What does that give you? The compiler is checking the code in the in-line example too. Your call doesn't add any extra checking. If you have to write GoToParkAndPlay? then you can extract it out then. Comments are part of the language too. And when there's no reuse involved the comment and the function call are equivalent, except the function code takes longer to develop.

The simplest thing is the method.

It is objectively more code to make them into separate functions if they are only called once.

Having each chunk in it's own method keeps each chunk simple and separate. Having them all in one method mixes abstractions, and is likely to create dependencies between the chunks. Common example, many people start declaring variables at the top and reusing them in every chunk, making extraction later much more difficult.

A bunch of parameters is a code-smell also. As far as reuse, I generally go by YagNi. One generally does not get the right granularity of reuse on the first try anyhow.

It is far easier to write the high level method in terms of calls to yet unwritten low level methods, kinda like writing your comments first, it helps clarify your intent and design in your own head. Once finished, you can easily go implement each method, and you get reuse for free later on. Comments are not part of the language by the way, they are sprinkled on to explain things that the language itself is incapable of expressing. Ask anyone who uses LotsOfShortMethods, and they'll tell you it allows them to develop far faster that they did when they used LongMethods?, it's one of the main reasons we like small methods, we can program faster that way.

Is PersonalChoiceElevatedToMoralImperative going on here?

No. the simple way is the correct way.

Personally I use short methods, but the downside is clear. It is very hard to understand the actual code being executed because everything is separate. People reading your code have a hard time figuring out what is actually happening. There is an implied state machine of what can be called when that is now totally lost unless you use DBC or an FSM. And personally I find a headline comment as clear. So when you make pronouncements about what is obvious and what is so, leave some room for honest disagreement. Calling is no more a meaningful check than is comment because nothing is being checked.

I think what's not clear is that the point of using those small methods is so you don't have to look at the code that is being executed. Why would you want to? The logic of what is being done is normally what you want to see, not how it's being done. I think large method fans are too accustomed to needing to see the actual code and just can't get over that. You should not have to look at implementation to follow the flow, the 'What' and the 'How' are completely different things. -- Person-A

FuzzyDistinctionBetweenInterfaceAndImplementation.
Things are interrelated by nature and we cannot fully hide that fact. Forcing them apart complicates the management of interrelations. It puts more "red tape" into interrelationship management.

Can you call LeaveHouse? before Shave? How do you know? You have to look at the call unless you are using DBC or FSM. Most people when they are look at code are making changes or finding problems. It's usually not instead of going to a movie. In these cases they usually need to know the code that is being executed. It's not good enough to just gloss. -- Person-B

Well, you can always look at shave and see, but at least you don't have to look at the other 7 implementations all the time. It is good enough to gloss over, until you hit the part you need to change. Then you look at that one. Mean while you've saved a ton of time not looking at stuff that you aren't working one. In a large method, I have to look at and digest the whole thing, all at once. Person-A

You are scanning headlines. It's not any more difficult than scanning method names.

Yes it is, the method names don't have implementation code between them getting in the way. It's easier to read code where you can just read every line, rather than having to read every 7th line and skip everything in between.

If you ran a restaurant, would you make a food menu that has the detailed descriptions separate from the dish titles?

Not a good example. Menu descriptions are LotsOfShortMethods. Does your menu, which mentions "smoked salmon", include detailed descriptions of how the fish is caught, cleaned, and smoked? I'd bet all of those implementation details are hidden within the "smoked salmon" method.

I don't know, some menus have rather long descriptions. Newspapers use it also, I would note (although some have a summary menu). Anyhow, the "headline" approach does not slow me down. If it slows you down, so be it. You know what bothers your eyes and brain, and I know what bothers mine (WetWare). To each their own. Viva La Difference, let's move on and AgreeToDisagree.

CategoryDocumentation