Separate The What From The How

I use two (code) refactoring rules.

OnceAndOnlyOnce - All code must appear in only one place.
SeparateTheWhatFromTheHow - A method should comprise one how, or two or more whats

Don't confuse with TheWhatButNotTheWhy

What's a "what"? How do you define "how"?

A "what" is a delegation to another method with a MeaningfulName. A "how" is a method that does one thing.

Example (in SmalltalkLanguage) - before

 moveRoom: aRectangle
   couch
      x: (aRectangle origin x + couch offset x)
      y: (aRectangle origin y + couch offset y).
   chair
      x: (aRectangle origin x + chair offset x)
      y: (aRectangle origin y + chair offset y).
   bookshelf
      x: (aRectangle origin x + bookshelf offset x)
      y: (aRectangle origin y + bookshelf offset y).

after

moveRoom: aRectangle | origin | origin := aRectangle origin. self moveCouch: origin. self moveChair: origin. self moveBookshelf: origin.

SeparateTheWhatFromTheHow is an approximation. If a method doesn't read "what-what-what..." or "how", but there is no obvious fix, leave it alone.

I am having trouble following this pseudocode. What is Origin? Why is everything a rectangle? What is moveX (where X = Chair, etc.) Is it a method or attribute?

This isn't pseudocode, it's code, smalltalk code. I'm no smalltalker, but as best I know, "| origin |" declares a variable local to the method, and the "moveX" things are selectors (like keyword arguments) for methods. The example isn't complete because it doesn't show how the "couch x: (aRectangle blah blah blah" stuff has been moved into other methods of whatever class moveRoom: belongs to.

HaveThisPattern: Alternate approach to the "what vs how" question is an old ModularProgramming maxim:

: "Functions should be managers or workers: A function should either do the work (being a worker) or delegate work to worker functions (making it a manager). Manager functions should not contain lots of code or algorithm, as their primary task is to determine what needs to be done, and then delegate it to others."

In the real world, managers do delegate most of the work to others. That is because it would be impossible to do the work themselves. In software, the manager can do all the work specific to its area of management. Another task is just another process in a case statement. I say this because I have the AntiPattern of the above - Manager functions should contain all the code relevant to their area of expertise, and their invocation should be through semantically clear minimal interfaces.

Manage Ports Get From Port Send To Port

Manage Indices

Get Indices Create Index Search Index Delete Index

Isn't this similar to the old separation of mechanism and policy?

SeparateTheWhatFromTheHow is the same as ComposedMethod. It is just worded differently. See also ShortMethods and IntentionNotAlgorithm. And WhatNotHow is also a synonym.

I was responsible for putting in the WhatNotHow page. I did not see this page before I did that.

The easy thing right now would be to change the pages I know of to point to this page, but unfortunately I prefer WhatNotHow because it is more concise. What, if anything, should be done? This is a OnceAndOnlyOnce issue!

If we were all perfect authors, maybe one page would do. But we are not, so maybe we need to keep all related pages: this page, ComposedMethod, WhatNotHow, IntentionNotAlgorithm, and the maxim about manager functions and worker functions, as we grope toward ever better written descriptions of what works for us programmers.

I like the following "after" version even more:

moveRoom: aRectangle | origin | origin := aRectangle origin. self couch move: origin. self chair move: origin. self bookshelf move: origin

This leads me to:

 furniture
   | answer |
   (answer = OrderedCollection new)
      add: self couch;
      add: self chair;
      add: self bookshelf;
      yourself.
   ^answer

 moveRoom: aRectangle
    | origin |
    origin := aRectangle origin.
    self furniture do: [:each | each move: origin]

Without being too much of a Luddite, may I ask some of these Smalltalkers to translate this stuff into a procedural form? Some sort of pseudocode or Java or C/C++, perhaps? It's a little hard to follow the discussion when it is written in an entirely different paradigm from the rest of the world.

See: FuzzyDistinctionBetweenInterfaceAndImplementation, SuccessStory, CategoryRefactoring, CategoryInfoPackaging, WhatNotHow