Separate The What From The How

I use two (code) refactoring rules.

  1. OnceAndOnlyOnce - All code must appear in only one place.
  2. 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
      x: (aRectangle origin x + couch offset x)
      y: (aRectangle origin y + couch offset y).
      x: (aRectangle origin x + chair offset x)
      y: (aRectangle origin y + chair offset y).
      x: (aRectangle origin x + bookshelf offset x)
      y: (aRectangle origin y + bookshelf offset y).
 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."

 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:

   | answer |
   (answer = OrderedCollection new)
      add: self couch;
      add: self chair;
      add: self bookshelf;

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

EditText of this page (last edited October 31, 2013) or FindPage with title or text search