Object Mentor Blog: Refactoring Exercise

Refactoring Exercise

Brett Schuchert — Thu, 04 Jun 2009 21:23:00 -0500

So I’ve written a somewhat ugly method with the intent of having people clean it up. Want to give it a try? Post your results and then I’ll show what I ended up doing in a few days (or after the activity dies down).

It’s in Java, but feel free to post in other languages. I’d be interested in seeing something in whatever language Michael Feathers happens to be deeply studying right now!-)

Oh, and if you feel like going “overboard” and using a few design patterns just because you can, I’d like to see that as well.

Here it is:

  public void take(int v) {
    if (currentMode == Mode.accumulating) {
      int digits = (int)Math.pow(10, (int)Math.log10(v) + 1);
      int x = stack.pop();
      x *= digits;
      x += v;
      stack.push(x);
    }

    if (currentMode == Mode.replacing) {
      stack.pop();
      stack.push(v);
      currentMode = Mode.accumulating;
    }

    if (currentMode == Mode.inserting) {
      int top = stack.peek();
      stack.push(top);
      stack.push(v);
      currentMode = Mode.accumulating;
    }
  }

"Refactoring Exercise" by mlb jerseys sale

Thu, 22 Jul 2010 04:42:53 -0500

http://www.superstonejerseys.com

"Refactoring Exercise" by Chris

Wed, 01 Jul 2009 17:30:10 -0500

@Brett

I think perhaps we are talking at cross-purposes. I am not objecting to the name “enter” in itself, nor to the subtle distinction between “pressing enter” and “completing an input”. I am objecting to the use of any interface-level concepts in the domain model.

In a RPN calculator, the domain interface requires three basic operations: putting in a number, putting in an operation, and reading out the current value.

Internally, of course, it maintains some sort of stack, but the state of that stack is evident only through operations that implicitly change the values at the top of the stack and through reading the current top value.

Similarly, there is some logic associated with knowing when a sequence of digits typed by the user is a new number ready to put onto the stack, but this matters only to the UI code. We can see that things like typing an individual digit or pushing an enter button are not in themselves meaningful concepts in the domain, because they make a difference only when they result in pushing a new number onto the stack.

This structure would have been immediately obvious had there been separation between the domain model (probably a class with only three public methods plus constructor) and the UI code (with whatever state machine might be appropriate to handle the individual key presses). But because in Uncle Bob’s version there is just the one huge Register class trying to do everything with many tiny methods, there isn’t even this basic separation of concerns and the levels of abstraction are all mixed up.

"Refactoring Exercise" by Andrei Vajna

Tue, 23 Jun 2009 14:02:25 -0500

I took a quick look to the current solutions, and it seems mine is veeery close to Peter Bona’s.


abstract class Mode {
  public abstract Mode void take(Stack stack, int v);

  public static final Mode accumulating = new Mode() {
    private int calculatePowerOfTen(int v) {
      return (int)Math.pow(10, (int)Math.log10(v) + 1);
    }

    Mode void take(Stack stack, int v) {        
      int top = stack.pop();  
      stack.push(top * calculatePowerOfTen(v) + v);
      // i chose to use the temp because it's more explanatory this way
      // and because pop() has side effects and i don't want to include it
      // in an expression
      // but i could have easily written
      // stack.push(stack.pop() * calculatePowerOfTen(v) + v);
      // it would be the same regarding functionality
      // but i feel it's more readable this way
      return this;
    }
  };

  public static final Mode replacing = new Mode() {
    Mode void take(Stack stack, int v) {
      stack.pop();
      stack.push(v);
      return Mode.accumulating;
    }
  };

  public static final Mode inserting = new Mode() {
    Mode void take(Stack stack, int v) {
      stack.push(stack.peek());
      stack.push(v);
      return Mode.accumulating;
    }
  };
}

The originial take method becomes:


public void take(int v) {
  currentMode = currentMode.take(stack, v);
}

Mode is an implementation of the State pattern. I preffered your initial use of constans and also, I used annonymous classes for conciseness. You could as well have used proper classes, subclassed from Mode base class.

The difference from Peter’s solution are little readability refactorings, like eliminating on of the temps in the accumulating mode with a method.

Two points I’d like to make to your problem: you didn’t specify what the purpose of the refactoring is, so I could well say that the already implemented solution is fine as it is. And second, “using a few design patterns just because you can” is bad! :)

"Refactoring Exercise" by Luca Minudel

Sun, 21 Jun 2009 12:19:41 -0500

public void take(int v) {

currentMode.take(stack, v);
  currentMode = new CurrentModeAccumulating();

...

class CurrentModeAccumulating : ICurrentMode {...}

class CurrentModeReplacing : ICurrentMode {...}

class CurrentModeInserting : ICurrentMode {...}

"Refactoring Exercise" by Brett L. Schuchert

Tue, 16 Jun 2009 22:25:01 -0500

Chris wrote:

On the contrary, it is describing not what the function does but when it should be called in terms of specific user actions.

I think you are a bit off the mark. Ultimately, the underling facade supporting some user interface needs to have the ability to represent logical operations from the perspective of the user.

Sure, this is not always a 1-to-1 mapping (and in fact it should not be so most of the time). However, there is a difference between “entering the digits of the number” and “starting the next number”.

So some questions I might ask:

What are the logical interactions?
How many steps do I want to make explicit in the design of my facade layer?
How will one design impact multiple potential user interfaces?
Can that one facade server all, or is it easy enough to adapt to make it a reasonable abstraction?
Does the facade as designed preclude some kind of interaction?
...

Here is an example I came across on a project in 1997…

The project allowed flight rebookings on Palm 7’s, the web, WAP enabled phones and smart two-way pagers. It worked well, it was ready for use and it was in production (well it was in a beta sense).

Then along came a new 2-way pager that used SMTP as its communication between the pager and the base. The average response time was 1 minute. The minimum was 30 seconds and the max was 3+ minutes.

We had designed several logical steps to change a flight (end to end):

Go to a URL/bookmark
Log in
Review itineraries
Select itinerary to change
Indicate desired change (earlier/later)
Select one from a list of options
Accept change fees
Log out

Ignoring logout, that’s 7 steps. On this new device, that would, on average, require 7 minutes.

We had a conflicting requirement to make a system that was faster than making a phone call. 7 minutes was off the mark by several minutes.

So we had to adapt the underlying interaction. We left the underlying service as is but we developed an application for the two-way pager. This application maintained a cache of itineraries and credentials.

The new interaction was:

Start application (no time, no hit)
Select itinerary and indicate earlier or later booking (hit one)
Select from option
Accept change fees

This was considered too long (three minutes), so we made it even simpler:

Select itinerary and provide a window (2 – 4 hours earlier)
Auto select change fees if < $250

So this made it fast enough, but it took away too much from the experience and was rejected. We actually had to bring the manufacturer on site to tell them there really were no other options.

Why do I bring all of this up at all?

When you are building a system, a part of its design is user interaction. Part of that is designing a system that accommodates all of the points of interaction that make the best possible user experience, removing was is not necessary (or relegating it to an alternative).

In this case, enter() is the name given for the logical idea of completing input on one number.

Can this be removed? Yes. Can a calculator designed without this interaction work with many different user interfaces? Yes (I’ve done it). Does it map well to the domain? YES.

The HP calculators have been around since the late 60’s (see http://www.hpmuseum.org/

So to take it away in fact could make the underlying solution less close to the domain and in fact result in a worse solution.

One person’s intention is another person’s “specific user actions”.

Discussing the “enter” function is taking a phenomenological perspective, removing it and discussing “indication completion” is moving towards the ontological.

Context dictates one approach as “better” than another – at least for now.

"Refactoring Exercise" by Chris

Sun, 14 Jun 2009 17:46:43 -0500

@Philip Schwarz

The thing is, calling a function “enter” like that isn’t intention revealing. On the contrary, it is describing not what the function does but when it should be called in terms of specific user actions. There is a place for event handlers like that, but it’s in your user interface modules. Why is any code in an internal class like this even aware of what the nature of the user interface is, never mind referring to specific user actions?

Again, there is a not-seeing-wood-for-trees problem here. If we were to expand the scope of the problem to include the user interactions - which is far beyond what the original function covered and not a mere refactoring, of course - then we should be creating an internal class to model the stack behaviour with interface methods representing domain concepts such as pushing a number onto the stack, applying an operator and showing the current top of the stack, and we should also have separate code to handle UI quirks like parsing single keystrokes and evaluating when they become triggers for certain meaningful actions in the problem domain.

"Refactoring Exercise" by Philip Schwarz

Sun, 14 Jun 2009 17:10:09 -0500

@Chris

You said:

I could immediately guess what isEmpty would mean from the calling code, and while it is only a single line long, it does represent a useful abstraction. On the other hand, despite knowing the general problem area we’re discussing, I still don’t see why the names take, dup, enter and accumulate are particularly helpful here. take seems rather arbitrary: neither it nor the name Register provide enough context for it to be a meaningful concept without further information.

OK..so while you find ‘isEmpty’ to be intention-revealing, the same is not true for Uncle Bob’s one-line methods.

If you look back 11 posts from Uncle Bob’s, you’ll see Brett’s firts follow-up post, in which he says:

By the way, this is the beginnings of a method to handle input for an RPN calculator. Input is more complex than I first imagined:

Initially digits are accumulating.
After pressing enter, the next digit will replace the top of the stack (the x register) because pressing enter duplicated the current top.
After executing an operator, e.g., + – / * !, typing a digit duplicates the top of the stack (while another operator uses what’s there).

Based on that, the following is possible:

The accumulate method is called that way because it tells the Calculator to go into a state in which it accumulates digits.
The take method is called that way because it takes the user’s input to the calculator.
The Register class is called that way because the Calculator has a number of register, e.g. x.
The dup method maps to the problem domain (or system metaphor) concept of duplicating the top of a stack
The enter method maps to the problem domain concept of pressing the calculator’s enter button.

So Uncle Bob has created methods that map to problem-domain abstractions and are therefore intention-revealing to anyone who knows enough about the problem domain. To make the code readable, he has hidden code that tells us HOW the problem solution is implemented, behind code that models WHAT happens in the problem domain.

You seem (to me) to be saying that Uncle Bob’s one-line methods make the code harder to read because they are not intention-revealing (to you because you don’t know enough about the problem domain), so the code would be better off (more readable) if instead of telling you about WHAT happens in the problem domain, it just told you HOW the solution to the problem is implemented e.g. using stack operations.

I disagree. Uncle Bob has chunked implementation details and hid them behind intention-revealing method names, so that people who know enough about the problem domain (e.g. anyone intending to maintain the code) can read his code more quickly and accurately.

"Refactoring Exercise" by Chris

Sun, 14 Jun 2009 00:56:15 -0500

@Philip Schwarz

I think the code you cited is an excellent example of taking a good rule of thumb to such an absurd extreme that it breaks.

I am amused by the fact that the one function in the proposed rewrite that does do something actually does two things; the name even describes (with no useful abstraction whatsoever) what those two things are. If iteration and alternation violate the Sacred Principle of Oneness enough to justify separating everything inside any pair of {} then surely sequencing does as well? I’m mildly surprised that the person who wrote that originally hasn’t yet died of old age waiting for an infinite recursion to finish! :-/

The tragic thing is that while messing around with dogmatic changes to achieve small functions for no particular benefit, the author has missed the wood for the trees. The first question I would ask about the original function is why this code is messing around so much with the details of another object. Tell, don’t ask:

public void pay()
{
  for (Employee e : employees)
  {
    e.pay();
  }
}

and on the Employee class:

public void pay()
{
  if (isPayDay())
  {
    deliverPay(payDue());
  }
}

Then we might consider further improving the function names, but cleaning those up requires knowledge of the context that hasn’t been provided in this example, so there’s not much we can do beyond renaming the calculation function to something more appropriate given that its purpose is defined by the value it returns.

Of course, this whole example is very artificial, as it’s unlikely that in a real system an Employee object would know how to make a payment without depending on other parts of the system anyway…

"Refactoring Exercise" by Chris

Sat, 13 Jun 2009 22:59:14 -0500

@Philip Schwarz

We seem to be overlapping here because of some funny delays in posting, so I don’t know if you’d seen my earlier posts that already addressed some of your points when you wrote your latest contribution. I’ll just briefly comment on a couple of your other points for now.

On the subject of Composed Method:

Divide your program into methods that perform one identifiable task. Keep all of the operations in a method at the same level of abstraction. This will naturally result in programs with many small methods, each a few lines long.

The first two principles I completely agree with. This is basic functional decomposition advice that has been around since the programming stone age (though alas many professional developers seem to have forgotten it shortly afterwards in their quest to objectify this and higher level language that).

But I can’t agree with the conclusion. I’ve worked on code in several fields, from mathematical modelling to instrument control, where it would be perfectly possible to have a function dozens, perhaps even hundreds, of lines long that did represent a single task with the implementation at the same level of abstraction throughout. Usually the control flow would be quite linear, but subdividing the logic further would just be an artificial break.

In any case, as I mentioned before, my objection is not to small functions as such, just to small functions that don’t really gain us any useful abstraction. To wit, I see a marked contrast between your comments on the Intention Revealing Message pattern with the isEmpty example and Uncle Bob’s take function that you quoted. In particular, I could immediately guess what isEmpty would mean from the calling code, and while it is only a single line long, it does represent a useful abstraction.

On the other hand, despite knowing the general problem area we’re discussing, I still don’t see why the names take, dup, enter and accumulate are particularly helpful here. take seems rather arbitrary: neither it nor the name Register provide enough context for it to be a meaningful concept without further information. dup betrays the underlying implementation, while enter randomly obscures the implementation despite operating at the same level of abstraction. The worst is accumulate, which doesn’t accumulate anything at all, despite having a common meaning along those lines when applied to a sequence in computer science literature; it actually changes the mode (and apparently in a way that only code related to the Register class is permitted to do, though the analogous functions for setting other modes are public). In fact, looking over the entirety of Uncle Bob’s code again, it is littered with one-liners that are never actually used, yet betray implementation details or at best rename something without providing any additional abstraction.

In short, reading Uncle Bob’s take function, I would have had to look up every single function it called anyway, to drop to a useful level of abstraction and work out what the underlying logic was, completely defeating the point of factoring out the individual routines. However, to work out what other code interacted with the take function, I would also have to analyse all code with access to the same instance of Register because the numerous small, public functions effectively expose the implementation anyway. Whatever happened to “Tell, don’t ask”?

As for the small methods vs. increased interactions issue, I don’t have much to add there. A few consultants can repeat the mantra as often as they like, but the evidence simply doesn’t support their conclusion. Increasing complexity is definitely a causal factor in making code harder to understand; this much is well supported by research. Moreover, it seems likely that there is a positive correlation between function length and function complexity, but it doesn’t follow that small functions automatically help readability. It does follow, however, that if the functions get so small that the complexity starts to increase because of all the added interactions, this harms readability.

"Refactoring Exercise" by Philip Schwarz

Sat, 13 Jun 2009 22:26:09 -0500

@Chris

I typed in that last method incorrectly…here is the correct version:

public void calculateAndDeliverPay(Employee e)
{
  Money pay = e.calculatePay();
  e.deliverPay(pay);
}

"Refactoring Exercise" by Philip Schwarz

Sat, 13 Jun 2009 22:13:28 -0500

@Chris

OK, so you have a copy of clean code…good…based on your opinion of one-line methods, I suspect that Heuristic G30 (Functions Should do One Thing) will give you a heart attack:

public void pay()
{
  for (Employee e : employees)
  {
    if (e.isPayDay())
    {
      Money pay = e.calculatePay();
      e.deliverPay(pay);
    }
  }
}

This bit of code does three things…This code would be better written as:

public void pay()
{
  for (Employee e : employees)
  {
    payIfNecessary(e);
  }
}

public void payIfNecessary(Employee e)
{
  if (e.isPayDay())
  {
    calculateAndDeliverPay(e);
  }
}

public void pay()
{
  Money pay = e.calculatePay();
  e.deliverPay(pay);
}

What do you think?

"Refactoring Exercise" by Philip Schwarz

Sat, 13 Jun 2009 22:03:27 -0500

@Chris

You said:

This is in marked contrast to, for example, Code Complete by Steve McConnell, in which the author describes “a mountain of research” on the subject and cites six distinct sources that do not support the benefits of very small functions.

Thanks for that, I will dig my copy out.

"Refactoring Exercise" by Philip Schwarz

Sat, 13 Jun 2009 21:58:59 -0500

@Chris wrote:

Why do we use functions? We use them to define an abstraction, to hide implementation details that are irrelevant to higher-level code. What are you abstracting by writing a single-line function like the ones in Uncle Bob’s example? Probably nothing. The problem doesn’t get any simpler by doing this.

On the contrary, although each individual method becomes trivially simple to follow, a reader now has to laboriously scan through the whole verbose mess to find enough context to understand what is actually happening. This is not an improvement, it makes things much more complicated.

Object Mentor have their own school of thought about clean code. They don’t claim their particular school to be right. They do claim that if you follow their teachings, you will learn to write code that is clean and professional. They say that there are other schools of thought, and other masters, that have just as much claim to professionalism as they do. While they present their opinions as “their” absolutes (the way they practice their art, they acknowledge that many of their recommendations are controversial, and that not everyone will agree with them.

In Clean Code, Uncle Bob kicks off his recommendations for functions with three key principles: they should be small, they should only do one thing, and all their statements should be at the same level of abstraction.

About function size, he says:

the first rule of functions is that they should be small, and that the second rule is that they should be smaller than that.

His experience has taught him that functions should be very small. Describing a program written by Kent Beck, he says:

every function in this program was just two, or three, or four lines long. Each was transparently obvious. Each told a story, And each led you to the next in a compelling order. That’s how short your functions should be!

Going back to the three principles (Small, Do One Thing, Same Level of Abstraction), you will recognise these as being the three components of Kent Beck’s Composed Method pattern:

Q: How do you divide a program into methods?
A: Divide your program into methods that perform one identifiable task. Keep all of the operations in a method at the same level of abstraction. This will naturally result in programs with many small methods, each a few lines long.

When describing the pattern, Kent Beck says:

The opportunity to communicate through intention revealing message names is the most compelling reason to keep methods small. People can read your programs much more quickly and accurately if they can understand them in detail, then chunk those details into higher level structures. Dividing a program into methods gives you an opportunity to guide that chunking. It is a way for you to subtly communicate the structure of your system.

And here is Kent Beck’s Intention Revealing Message pattern:

Q: How do you communicate your intent when the implementation is simple?
A: Send a message to “self”. Name the message so that it communicates what is to be done rather than how it is to be done. Code a simple method for the message.

Here is my translation into Java of one of his Smalltalk examples:

Collection isEmpty()
{ 
    return this.size() == 0 
}

When describing the pattern, Kent Beck says:

What is going on? Communication. Most importantly, one line methods are there to communicate...Intention revealing messages are the most extreme case of writing for readers instead of the computer…methods that separate intention (what you want done) from implementation (how it is done) communicate better to a person.

Brett’s original ‘take’ method is NOT a composed method.

It doesn’t do just one thing (try describing it!): it is checking and modifying some state, doing some maths, manipulating a stack, and doing different things in different states.

Its statement are not at the same level of abstraction: on one line it is doing a low-level computation of the number of digits in a value, in others it using that number to compute a higher level function, in others it is manipulating a stack.

The method is not short: while it is not long, it is not a few lines.

Also, the method does not delegate to intention-revealing methods. It just exposes you in one go to all the gory details of how it does what it does.

If instead you take Uncle Bob’s ‘take’ method for the ‘inserting’ mode:

public void take(Register r, int v) {
  r.dup();
  r.enter(v);
  r.accumulate();
}

It is much more composed than the original method, and its calls to r.dup(), r.enter(...), and r.accumulate() (examples of the single-line methods you object to) are very similar in their effect to invocations of intention-revealing methods: by calling them, the ‘take’ method tells you what it is doing, rather than how it is doing it (e.g. by manipulating a low-level stack or setting a class variable).

Regarding your concern about ‘laboriously scanning through the whole verbose mess to find enough context to understand what is actually happening.’, this is acknowledged by the main proponents of small methods as a price worth paying.

In Refactoring, Fowler writes:

The object programs that live best and longest are those with short methods. Programmers new to objects often feel that no computation ever takes place, that object programs are endless sequences of delegation. When you have lived with such a program for a few years, however, you learn just how valuable all those little methods are. All of the payoffs of indirection – explanation, sharing, and choosing – are supported by little methods

There is still an overhead to the reader of the code because you have to switch context to see what the subprocedure does….the real key to making it easy to understand small methods is good naming. If you have a good name for a method you don’t need to look at the body.

The net effect is that you should be much more aggressive about decomposing methods. A heuristic we follow is that whenever we feel the need to comment something, we write a method instead. Such a method contains the code that was commented but is named after the intention of the code rather than how it does it. We may do this on a group of lines or on as little as a single line of code. We do this even if the method call is longer than the code it replaces, provided the method name explains the purpose of the code. The key here is not method length but the semantic distance between what the method does and how it does it.

In Smalltalk Best-Practice Patterns, Kent Beck writes:

Following the flow of control in programs with many small methods can be difficult. Novice Smalltalk programmers often complain that they can’t figure out where any “real” work is getting done. As you gain experience, you will need to understand the flow of control through several objects less often. Well chosen message names let you correctly assume the maning of invoked code.

And in Implementation Patterns, Kent Beck says:

Code readers need to solve several problems that provide opposing influences on the size of methods. When reading for overall structure, seeing lots of code at once is valuable. ... The same big method that helped me orient myself becomes a hindrance when I turn to trying to understand the code in detail….Simultaneously supporting browsing and digesting is the challenge of the code author who is dividing logic into methods. I find that my code reads best when I break it into relatively small methods (at least by C standards).

"Refactoring Exercise" by Chris

Sat, 13 Jun 2009 19:00:48 -0500

Apologies if this post is a duplicate; I seem to be having some trouble replying here today.

@Philip Schwarz

Regarding the “small functions = good” claim I criticised, the first source that comes to mind is Clean Code by Uncle Bob himself, which has this to say on the subject:

The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that. This is not an assertion that I can justify. I can’t provide any references to research that shows that very small functions are better. [...] What this experience has taught me, through long trial and error, is that functions should be very small.

Of course, there are numerous other sources, from web sites to in-house style guides, that claim that functions should be no longer than one screen/50 lines/some other arbitrary limit. Googling “functions should be short” appears to turn up plenty of examples.

This is in marked contrast to, for example, Code Complete by Steve McConnell, in which the author describes “a mountain of research” on the subject and cites six distinct sources that do not support the benefits of very small functions.

"Refactoring Exercise" by Chris

Sat, 13 Jun 2009 13:56:46 -0500

Apologies if the first part of this post is a duplicate; I seem to be having some trouble replying here today.

@Philip Schwarz

If you’d like to debate further, I’ll be happy to defend my argument, but please allow me to clarify a couple of things immediately just to avoid talking at cross-purposes.

Firstly, I am not against using small functions in general. However, I think the value of a function, at least from a readability perspective, is dictated by the amount of abstraction it enables rather than by the number of lines of code it contains. A corollary to this is that functions of literally only one or two lines, which don’t have space to raise the level of abstraction very much, are often a warning sign to me, like seeing a class full of get/set methods for individual private data items and not much else. Sometimes these mechanics are justified, but often they are clues that the responsibilities and abstractions are broken.

Secondly, regarding my observation about locating the start-up code, of course you can fire up an IDE and use it to help you navigate code. My point was that in the original code I didn’t have to, because I’d comprehended the mechanics entirely just from reading the code, probably in less time than it would take to load that IDE. I find it hard to reconcile this with the claim that the longer code that requires IDE support to navigate with reasonable efficiency is more readable.

I notice that you’ve just replied again, asking about the “small functions = good” claim I criticised. The first source that comes to mind is Clean Code by Uncle Bob himself, which has this to say on the subject:

The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that. This is not an assertion that I can justify. I can’t provide any references to research that shows that very small functions are better. [...] What this experience has taught me, through long trial and error, is that functions should be very small.

"Refactoring Exercise" by Chris

Sat, 13 Jun 2009 13:36:30 -0500

@Philip Schwarz

If you’d like to debate further, I’ll be happy to defend my argument, but please allow me to clarify a couple of things immediately just to avoid talking at cross-purposes.

Firstly, I am not against using small functions in general. However, I think the value of a function, at least from a readability perspective, is dictated by the amount of abstraction it enables rather than by the number of lines of code it contains. A corollary to this is that functions of literally only one or two lines, which don’t have space to raise the level of abstraction very much, are often a warning sign to me, like seeing a class full of direct get/set methods for individual private data items and not much else. Sometimes these mechanics are justified, but often they are clues that the responsibilities and abstractions are broken.

"Refactoring Exercise" by Philip Schwarz

Sat, 13 Jun 2009 13:21:45 -0500

@Chris wrote:

Sorry, but I just can’t agree with this. Breaking things down into numerous very short methods like that actively harms readability, and it’s long past time people stopped dogmatically repeating “small functions = good” as if it’s some self-evident truth

Could you please elaborate further?

Do you have a particular time in mind when people dogmatically kept repeating that equation as if it was self-evidently true…was it this decade? was it the previous one?

And who was it that did this?, do you have particular personalities/methodologies in mind?

I am genuinely interested, and would be grateful if you could tell me more about this, or just give me some pointers.

"Refactoring Exercise" by Philip Schwarz

Sat, 13 Jun 2009 12:01:50 -0500

@Chris

Thank you for taking the time to explain why you think that rather than improving readability, breaking code down into many very short methods actually makes it harder to read. I was hoping someone would care enough to respond, and find the energy to do it.

You made several points, which I will tackle in separate posts.

I’ll start with a minor one.

You said: it took me a couple of minutes just to be sure of the entry point in Uncle Bob’s example that corresponded to the original function.

I pasted Uncle Bob’s code, a single class called Register, in an empty Java project in the Eclipse IDE, and opened up the class with the default Project Explorer, which showed the method signatures of the class, and immediately revealed only three public methods: insert(), replace(), and take(int), the latter clearly corresponding to the original function.

"Refactoring Exercise" by Chris

Fri, 12 Jun 2009 17:32:56 -0500

Philip Schwarz wrote:

In my view, while Uncle Bob’s solution is much longer, it is much more readable.

Sorry, but I just can’t agree with this. Breaking things down into numerous very short methods like that actively harms readability, and it’s long past time people stopped dogmatically repeating “small functions = good” as if it’s some self-evident truth.

Why do we use functions? We use them to define an abstraction, to hide implementation details that are irrelevant to higher-level code. What are you abstracting by writing a single-line function like the ones in Uncle Bob’s example? Probably nothing. The problem doesn’t get any simpler by doing this.

On the contrary, although each individual method becomes trivially simple to follow, a reader now has to laboriously scan through the whole verbose mess to find enough context to understand what is actually happening. This is not an improvement, it makes things much more complicated.

As a result, it took me a couple of minutes just to be sure of the entry point in Uncle Bob’s example that corresponded to the original function. This was not helped by having several methods on different but intimately related types sharing the same name, compounded by virtuality in one case. I’d read and understood the mechanics of the entire original code snippet in far less time.

As for the cyclomatic complexity, of course we want to keep the logic straightforward, but let’s be serious: we’re talking about a single real decision here, a simple dispatch based on what appears to be a choice of three possible modes. The consequences of that decision affect a single piece of shared state (the stack) and are defined by a single extra input value (the parameter to the take function). Distributing such simple logic across 14 different functions over more than 80 lines of code is madness.

Moreover, the decision is based on a simple value, not a type, so obscuring it by using an enumeration/virtuality trick where a simple switch or if-chain would do is unhelpful. Use an enumeration for the possible states, sure. Pull out a function that switches on the current state and dispatches to one function per state accordingly, by all means. But the rest is just trying to be clever, and I don’t see any advantage at all, never mind anything to justify the extra verbosity and clutter introduced.

In a nutshell, this problem isn’t even close to the size and complexity where patterns like State and Visitor pull their weight, nor is there any evidence that it is likely to become so any time soon. If dogma is appropriate to a problem like this, I suggest that You Ain’t Gonna Need It would have been a better choice.

"Refactoring Exercise" by Philip Schwarz

Wed, 10 Jun 2009 18:13:37 -0500

What a coincidence that Uncle Bob’s solution should appear straight after the Haskell one. I say this partly because these are the two solutions that stand out the most (in my view), but more importantly, because while they are so different, they both stand out (again, in my view) as the most readable.

My first reaction when I saw Uncle Bob’s solution, straight after the extreme succinctness of Haskell, was something along the lines of: what a huge contrast…how very long Bob’s solution is compared to the Haskell one…how can it take so much code to implement the same functionality?...

But then I started going back to Bob’s code, again and again, and once I took into account the huge expressiveness gap between the functional and OO paradigms, I have to say that I think that Bob’s solution is just as remarkable as the Haskell one in terms of its extreme readability.

Which of the solutions you have seen would you prefer to maintain?

This is a master at work, producing extremely readable code.

Brett’s original snippet, the one he asked us to refactor, was a single method with 15 lines of code, and a Cyclomatic Complexity (CC) of 4.

Bob has replaced this with 14 methods: nine one-liners, three two-liners, one three-liner, and one six-liner (the magnitude method). While the magnitude method has a CC of 3, all other methods have a CC of 1.

The result is some seriously readable code. No conditionals. Most of the time you are looking at a one-line method! A few times, it is a 2 or 3 line method. Also, while there is still some relatively high CC and high line-count in the system, it has been relegated to a single method (magnitude), which thanks to a very clear name and responsibility, won’t necessarily need to be read to understand all the rest of the code.

James Ladd said:

I’d like to play devils advocate and say that the method [Brett’s original] doesn’t need refactoring, since it is only 13 statements and not hard to understand. Why should you refactor this method? Note that some of the current refactorings come out to more than 13 statements and don’t necessarily add anymore clarity.

In my view, while Uncle Bob’s solution is much longer, it is much more readable.

I’ll conclude with a quote from Uncle Bob’s Clean Code:

the ratio of time spent reading vs. writing is well over 10:1. We are constantly reading old code as part of the effort to write new code.
Because this ratio is so high, we want the reading of code to be easy, even if it makes the writing harder. Of course there’s no way to write code without reading it, so making it easy to read actually makes it easier to write.
There is no escape from this logic. You cannot write code if you cannot read the surrounding code. The code you are trying to write today will be hard or easy to write depending on how hard or easy the surrounding code is to read. So if you want to go fast, if you want to get done quickly, if you want your code to be easy to write, make it easy to read.

"Refactoring Exercise" by Brett L. Schuchert

Tue, 09 Jun 2009 21:42:54 -0500

Philip Schwarz wrote:

But what does violating command/query separation buy you? Unless the violation pays for itself, how about avoiding it by simply pushing the pop() (pun not intended) out of determineNewTop, and explicitly passing the popped value into the method?:

I like it. In fact, I made that change and you’ll see it in the next exercise.

Thanks!

"Refactoring Exercise" by Vincent Burns

Tue, 09 Jun 2009 19:11:35 -0500

Erlang version

obligary use of processes and message passing

start() ->
    F = fun(Mode, [Top | Stack], F) ->
        receive
        {take, V} ->
             case Mode of
             accumulating ->
                 Digits = round(math:pow(10, round(math:log10(V) + 1))),
                 F(Mode, [Top * Digits + V | Stack], F);
             replacing ->
                 F(accumulating, [V | Stack], F);
             inserting ->
                 F(accumulating, [V, Top, Top | Stack], F)
             end
        end
    end,
    spawn(F).

and a version without the spawn and messages

take({accumulating, [Top | Stack]}, V) ->
    Digits = round(math:pow(10, round(math:log10(V) + 1))),
    {accumulating, [Top * Digits + V | Stack]};
take({replacing, [_ | Stack]}, V) ->
    {accumulating, [V | Stack]};
take({inserting, [Top | Stack]}, V) ->
    {accumulating, [V, Top, Top | Stack]};

"Refactoring Exercise" by Philip Schwarz

Tue, 09 Jun 2009 18:21:00 -0500

@Brett L. Schuchert

You said: the determineNewTop method both changes the stack (with a pop) and returns a value. Violates command/query separation, but it is also a private method, so I’m not as concerned about that violation.

But what does violating command/query separation buy you? Unless the violation pays for itself, how about avoiding it by simply pushing the pop() (pun not intended) out of determineNewTop, and explicitly passing the popped value into the method?:

  public void take(int value) {
    if (currentMode == Mode.accumulating) 
      value = determineNewTop(stack.pop(), value);

    if (currentMode == Mode.replacing) 
      stack.pop();

    stack.push(value);
    currentMode = Mode.accumulating;
  }

  private int determineNewTop(int top, int value) {
    int newTopValue = top;

    String digits = Integer.toString(value);
    while(digits.length() > 0) {
      newTopValue *= 10;
      newTopValue += Integer.parseInt(digits.substring(0,1));
      digits = digits.substring(1);
    }

    return newTopValue;
  }

And maybe, since you tolerated modifying input parameter ‘value’ in the ‘take’ method, you may want to do the same thing in ‘determineNewTop’: drop ‘newTopValue’ and just modify input parameter ‘top’.

"Refactoring Exercise" by Philip Schwarz

Tue, 09 Jun 2009 16:47:49 -0500

@Mike Bria

Neat…I like the fact that you got the actOn methods to shield the reader from the implementation details of stack manipulation….but wait….in Accumulater you didn’t go the whole way… shouldn’t its actOn method be calling something like adjustTopBy(value), rather than stack.push(topAdjustedBy(value))?

"Refactoring Exercise" by Phil

Tue, 09 Jun 2009 14:10:55 -0500

I don’t know about refactoring this short method, but if your goal is an rpn calculator program, you can see mine on my blog of programming etudes at http://programmingpraxis.wordpress.com/2009/02/19/rpn-calculator/.