An introduction to contemporary web application techniques

February 8th, 2014

I just attended CodeJam: Cutting edge web application development, a two-days course taught by Gabriele Lana and Sandro Paganotti and organized by Avanscoperta. (Disclaimer: I also offer courses through Avanscoperta and I had previously worked together with Gabriele.)

What was it like? In short, it’s like watching the reasoning, techniques and tools of two master software craftsmen at work. This was not an easy tutorial; the process was not simplified to make it easier to follow. Gabriele and Sandro applied all of their usual tools and process. This is the main value of the course; you can find as many Node or Angular tutorials, books and videos as you want. What you will not easily find is how accomplished Node or Angular professionals actually go about their business.

Gabriele in particular is fond of the “play by play” video series by Peepcode, where you can watch over the shoulder of an accomplished professional how they solve a problem. There is a lot of practical, untold information in that; information that we as a community don’t yet have a way of sharing. It’s about technique; how you use the shell, the editor, the keyboard. How you use screen real estate. What tradeoffs you make when you have to choose finessing versus delivering.

My particular interest in this course was to get up to speed on contemporary techniques for building web application. The old school of building applications by serving a new page of procedurally-generated html at every request is, well, old school. The new school is a single html page that contains a full application written in Javascript, while the server provides only REST persistence services.

The main gist of the course is that Sandro and Gabriele build an order-taking application for a restaurant. There is a mobile site that will be used by the waiter taking orders on a mobile phone, and a kitchen site that will be used by the cooks to see what dishes have been requested, and signal that the dishes are ready. The application is built with Angular in the frontend, and Node in the backend.

Participants follow the development on a Git repository, were a sequence of stages is saved in different branches. You could follow what the trainer was doing on your own machine and make experiments; or you could just watch what the trainer was doing, and listen to what he was saying. It didn’t matter if you didn’t complete the section (I rarely could) because the next stage would start from a fresh checkout of the next branch from Git.

The pace of the course was intense. The two trainers packed a *lot* of useful information. They showed different ways of doing things; for instance, the kitchen web site was built on just two files (one html and one js) and received events from the backend via websockets. The mobile site instead was built on a rails-like directory layout, with separate folders for models, controllers, etc; and it received events from the backend using Server-Side Events. Gabriele showed many different Node and Mongo techniques and libraries; Sandro showed many different Angular techniques.

Of particular interest was project automation with Grunt, which integrated many different tools together. For instance, whenever you saved a file, it would automatically run JSHint (check code style) and Karma (run the automated tests) and then reload the application in the browser. The initial directory layout was built with Yeoman. The introduction of Javascript and CSS libraries was managed by the Bowell package manager.

Gabriele explained his screen management philosophy: he uses a tiling window manager; how he completely remapped his modifier keys to type faster and with less strain on his body; how he uses Vim, how he uses the Unix shell.

I was impressed with Node. It’s an engineering marvel.

Last but not least, I should mention the course organizer Alberto Brandolini who provided us with delicious food during the day, lunch and evening. Thanks Alberto!

I invite you to check out the repository on Github. I’m very happy I attended this course!

Il mio corso di TDD

December 27th, 2013

TL;DR: what my public TDD course is about.

Imparare il TDD

In gennaio terrò il mio primo corso pubblico di TDD. Grazie ad Alberto Brandolini che lo ha organizzato.

La promessa del TDD

Scrivere programmi che funzionano correttamente gia dalla prima volta che vengono messi in produzione. Sentirsi dire dal cliente che i pochi difetti riscontrati si verificano talmente di rado che non vale neanche la pena di correggerli.

Arriva il cliente con una nuova richiesta. Ha cambiato idea di nuovo. Il nuovo requisito coinvolge una serie di nuovi casi speciali. Non è un problema: concordiamo con il cliente alcuni esempi concreti e lo risolviamo. Il nostro codice è malleabile: il nuovo requisito del cliente spesso richiede solo di creare nuove implementazioni di interfacce esistenti; in questi casi il design supporta facilmente l’introduzione del nuovo requisito. In altri casi invece dobbiamo modificare la struttura del codice per poter inserire bene il codice nuovo. Lo facciamo in maniera controllata, a piccoli passi. Il nostro codice è semplice perché è stato sviluppato a partire dai test: la maggior parte delle volte, il codice che abbiamo prodotto era molto più semplice di quello che ci aspettavamo di dover scrivere.

Ti ricordi? Una volta scrivevamo codice per, tipo, una settimana. Poi passavamo una o due settimane a farlo funzionare, debuggando con le scritte sulla console. Ora il debugging non lo facciamo quasi più. Il codice viene pensato, testato, scritto ed integrato nel giro di minuti, non giorni.

Le difficoltà

Non è stato facile. Io ci ho messo anni per cominciare a capire come funziona il TDD. Sono stati anni produttivi: ogni nuovo gradino di comprensione mi ha permesso di scrivere codice migliore. E ogni nuovo gradino diventava un plateau da cui non era facile scorgere quale fosse il prossimo passo.

Mi sono dovuto ricredere su tante cose. Ho imparato a tenere i framework, il sistema operativo, le librerie al loro posto, per essere sicuro di mantenere il controllo della situazione. Non voglio essere alla mercé di quello che un framework può o non può fare, dei suoi bug e delle sue idiosincrasie. Il codice della mia applicazione adesso è separato dal codice che serve a parlare con il framework.

Ho imparato che il design è importante. Carlo Bottiglieri ha detto “Se il design non lo sai fare, il TDD non te lo insegna.” E’ per questo che dopo i primi successi con il TDD, non riuscivo a migliorare. Ho cercato chi potesse insegnarmelo; ho comprato libri di seconda mano perché l’argomento “design” è talmente fuori moda che i libri non li ristampano più. Alcuni libri che pure avevo letto prima, come il famoso libro dei pattern, non mi avevano detto granché. Ora li rileggo e capisco meglio che cosa vogliono dire.

Ho capito che il design è un modo di pensare; Francesco Cirillo ripeteva “E’ semplice ma non è facile”. Ora capisco che l’idea che avevo io di “semplice” era tutta sbagliata. Capisco anche perché molti programmatori confondono il “semplice” con il “facile”, perché anch’io ho vissuto questa confusione. Coesione e accoppiamento adesso hanno un senso; le vedo nel codice.

E non è finita. Continuo a imparare nuove cose, da libri, blog, colleghi e situazioni sul lavoro. E’ bello quando affrontiamo un problema in pair programming, facendo TDD come si deve e quindi scrivendo solo il minimo che serve per fare passare il test, rimuovendo la duplicazione a ogni passo, e otteniamo codice molto più semplice del previsto. Salta fuori che il TDD è una tecnica di design… proprio come dicevano i libri!

Il corso di TDD

Dal 2007 al 2012 ho lavorato in Sourcesense/XPeppers come coach del team Orione. Abbiamo affrontato molti problemi con TDD. Abbiamo insegnato il TDD (con tutti i limiti della nostra comprensione dell’argomento) presso i nostri clienti. Abbiamo fatto un corso pubblico di TDD di un giorno, che ha avuto un discreto successo.

Dall’aprile 2012 sono tornato consulente indipendente. Faccio il coach freelance presso organizzazioni che vogliono migliorare la maniera in cui lavorano con il software.

Il corso di due giorni sul TDD è stato provato più volte presso i nostri clienti, insieme al mio collega coach Antonio Carpentieri. Nel maggio del 2013 sono stato invitato dagli amici di DotNetToscana a fare un corso di TDD di due giorni. Dopo quell’esperienza ho sentito che il corso era pronto per essere presentato al pubblico.

La prospettiva

Qual’è la prospettiva attraverso cui mostro il TDD?

  • Il TDD è divertente. È semplice. Cerco sempre il senso del semplice e del divertente nella programmazione. Per questo sono molto sospettoso quando sento parlare di “framework per testare X”. Mi puzza di complicazione. Per iniziare a fare TDD non c’è nemmeno bisogno di xUnit.
  • Il TDD è una tecnica di design. Per me non è uno slogan, è una cosa che pratico per davvero. Per questo quando parlo di TDD parlo anche e soprattutto di come fare design.
  • Si parte sempre da una user story. Sviluppiamo per realizzare una richiesta del cliente; per questo il primo test spesso è un acceptance test.
  • Acceptance test non significa end-to-end test. Sono due concetti ortogonali; un AT può anche essere un test end-to-end, ma spesso non lo è.
  • Separa la parte facile da testare da quella difficile da testare. Concentra tutta la logica interessante nella parte facile da testare.

I miei maestri? Ho imparato da Francesco Cirillo e Carlo Bottiglieri. Considero fondamentali il libro di Kent Beck, Test-Driven Development: By Example, il libro di Steve Freeman e Nat Pryce, Growing Object-Oriented Software Guided By Tests. Condivido molte delle cose che scrivono Arlo Belshee e J.B. Rainsberger. Trovo utili i video di Robert Martin e quelli di Piergiuliano Bossi.

In conclusione

Per me il TDD è uno strumento per migliorare. Senza il TDD, ogni programmatore arriva al suo livello naturale di competenza e si ferma lì. Con il TDD, e il design che devi imparare per fare bene TDD, hai un percorso di miglioramento che non finisce mai. Il mio corso può esserti utile se:

  • hai provato qualche volta a fare TDD, ma non è rimasto nella tua pratica quotidiana.
  • Hai fatto qualche progetto con TDD ma il codice che ne è uscito fuori era un pasticcio.
  • Vorresti iniziare a fare TDD ma non sai da dove cominciare.
  • Fai correntemente TDD e hai qualche dubbio da sciogliere per passare al prossimo livello.
  • Senti sempre parlare di “design” ma non hai mai trovato un libro che te lo spieghi bene.

Se ti riconosci in uno di questi casi, probabilmente posso aiutarti, perché sono stadi da cui sono passato anch’io.

Notes on exception handling

November 20th, 2013

If a function be advertised to return an error code in the event of difficulties, thou shalt check for that code, yea, even though the checks triple the size of thy code and produce aches in thy typing fingers, for if thou thinkest “it cannot happen to me”, the gods shall surely punish thee for thy arrogance.

Henry Spencer’s 10 Commandments for C Programmers

In the olden days, before Exceptions were invented, we wanted to write code like this:

// Called when the user presses the "triple" button
void onTripleButtonPressed() {
  String valueEntered = readValueFromField();
  int valueToDisplay = triple(stringToInteger(valueEntered));
  displayResult(integerToString(valueToDisplay));
}

int triple(int value) {
  return value * 3;
}

Unfortunately, we were forced to write code like this instead:

int onTripleButtonPressed() {
  StringHolder valueEntered = new StringHolder();
  int resultCode = readValueFromField(valueEntered);
  if (isError(resultCode))
    return resultCode;

  IntHolder valueAsInteger = new IntHolder();
  resultCode = stringToInteger(valueAsInteger, valueEntered.value);
  if (isError(resultCode))
    return resultCode;

  resultCode = triple(valueAsInteger);
  if (isError(resultCode))
    return resultCode;

  StringHolder valueToDisplay = new StringHolder();
  resultCode = integerToString(valueToDisplay, valueAsInteger.value);
  if (isError(resultCode))
    return resultCode;

  resultCode = displayResult(valueToDisplay.value);
  if (isError(resultCode))
    return resultCode;

  return OK; // :-)
}

private int triple(IntHolder valueAsInteger) {
  int result = valueAsInteger.value * 3;
  if (isOverflow(result)) 
    return ERROR_OVERFLOW;
  valueAsInteger.value = result;
  return OK;
}

Yes, we were FORCED to check the result of each and every operation. There was no other way to write reliable software. As you can see:

  • Code size is more than three times
  • Logic becomes obscure
  • Functions are forced to return two values; the intended result AND an error code.
  • You always, always, always had to return an error code from all functions.

There was no alternative, until exceptions came along. Then we were finally able to write simple code in a reliable way:

// Called when the user presses the "triple" button
// Exceptions are handled here
void onTripleButtonPressed() {
  try {
    tryOnTripleButtonPressed();
  } catch (Exception e) {
    alertUser(e.getMessage());
  }
}

// Business logic is handled here
private void tryOnTripleButtonPressed() {
  String valueEntered = readValueFromField();
  int valueToDisplay = triple(stringToInteger(valueEntered));
  displayResult(integerToString(valueToDisplay));
}

In this example, all exception handling is centralized at the point where the GUI gives control to our code. The code that performs what the user really wanted is in another function, which contains exactly the same clean code of the first example.

Thus, the invention of exception handling allows us to cleanly separate code that performs the happy path, and code that handles the many possible exceptional conditions: integer overflow, I/O exceptions, GUI widgets being improperly configured, etc.

What you saw in the previous example is the

Fundamental Pattern of Exception Handling: centralize exception handling at the point where the GUI gives control to our code. No other exception handling should appear anywhere else.

It turns out that the Fundamental Pattern of Exception Handling is the only pattern that we need to know. There are other cases where we are tempted to write a try-catch, but it turns out that we nearly always have better ways to do it.

Antipattern: nostalgia (for the bad old days)

There is an ineffective style of coding that we sometimes see in legacy code:

void onTripleButtonPressed() {
  String valueEntered = null;
  try {
    valueEntered = readValueFromField();
  } catch (Exception e) {
    logger.log(ERROR, "can't read from field", e);
    return;
  }

  int valueEnteredAsInteger = 0;
  try {
    valueEnteredAsInteger = Integer.parseInt(valueEntered);
  } catch (Exception e) {
    logger.log(ERROR, "parse exception", e);
    return;
  }

  int valueToDisplay = 0;
  try {
    valueToDisplay = triple(valueEnteredAsInteger);
  } catch (Exception e) {
    logger.log(ERROR, "overflow", e);
    return;
  }

  try {
    displayResult(integerToString(valueToDisplay));
  } catch (Exception e) {
    logger.log(ERROR, "something went wrong", e);
    return;
  }
}

As you can see, this is just as bad as the olden days code! But while in the old times we had no alternatives, now we do. Just use exceptions the way they were intended to.

Stay up no matter what

Sometimes there is a feeling that we should write code that “stays up no matter what happens”. For instance:

private void tryOnTripleButtonPressed() {
  String valueEntered = readValueFromField();
  int valueToDisplay = triple(stringToInteger(valueEntered));

  try {
    sendEmail(userEmail, "You tripled " + valueEntered);
  } catch (Exception e) {
    logger.log(WARNING, "could not send email", e);
    // continue
  }

  displayResult(integerToString(valueToDisplay));
}

Here we have added an email confirmation; whenever the user presses the button, they will also receive an email. Now we should ask ourselves which of the two:

  1. is the sending of the email an integral and fundamental part of what should happen when the user presses the button?
  2. Or is it an accessory part should never stop the completion of the rest of the action?

This is a business decision. If the business decides on 1., then we should remove the try-catch. By applying the Fundamental Pattern, proper logging of the exception will be done elsewhere. We end up with:

private void tryOnTripleButtonPressed() {
  String valueEntered = readValueFromField();
  int valueToDisplay = triple(stringToInteger(valueEntered));
  sendEmail(userEmail, "You tripled " + valueEntered);
  displayResult(integerToString(valueToDisplay));
}

Clean code again. Yay!

If the business decides on 2., then we cannot allow sendMail to throw exceptions that might stop the processing of the user action. What do we do now? Do we have to keep the try-catch?

The answer is yes, but out of the way. There are two ways to do this: the easy way and the simple way. If you do it the easy way, you will move the try-catch inside the sendMail function. You will get code like this:

private void tryOnTripleButtonPressed() {
    String valueEntered = readValueFromField();
    int valueToDisplay = triple(stringToInteger(valueEntered));
    sendMail(userEmail, "You tripled " + valueEntered);     
    displayResult(integerToString(valueToDisplay));
  }

private void sendMail(EmailAddress email, String message) {
  try {
      trySendEmail(email, message);
  } catch (Exception e) {
    logger.log(WARNING, "could not send email", e);
    // continue
  }
}

You have moved exception handling for sending mail to a dedicated function (good). However, you still have complicated code tightly coupled to the user action. The sending of email, which is an accessory operation, makes understanding the fundamental operation more difficult (bad!)

What is the simple way, then? In the simple way we eliminate the tight coupling betweeen tripling the number and sending the email. There are several patterns that we might use; a typical choice would be “publish-subscribe”. We set up a subscriber that waits for the “User Pressed the Triple Button” event. In the main onTripleButtonPressed function we don’t know nor care what the subscriber does. It might send email, write logs, compute statistics, or maybe distribute the event to a list of other subscribers. We don’t know nor care! The code looks like this:

private void tryOnTripleButtonPressed() {
  String valueEntered = readValueFromField();
  int valueToDisplay = triple(stringToInteger(valueEntered));
  subscriber.notifyTripled(valueEntered);
  displayResult(integerToString(valueToDisplay));
}

In the Simple way, the Fundamental Pattern has been respected: for the subscriber object, the start of the processing is within the notifyTripled method. We have clean and loosely coupled code.

Avoid resource leaking

Another time when we are tempted to use a try-catch in violation of the Fundamental Pattern is when we open some resource that must be closed.

void doSomethingImportant() {
  Reader reader = null;
  try {
    reader = new FileReader("foo bar");
    doSomethingWith(reader);
    reader.close();
  } catch (Exception e) {
    if (null != reader) {
      reader.close();
    }
    // report the exception to the callers
    throw new RuntimeException(e);
  } 
}

It is correct that we close the reader in the event that something within doSomethingWith throws an exception. But we don’t want the catch; a finally clause is better:

void doSomethingImportant() throws IOException {
  Reader reader = null;
  try {
    reader = new FileReader("foo bar");
    doSomethingWith(reader);
  } finally {
    if (null != reader)
      reader.close();
  } 
}

This way, we don’t even need to worry about rethrowing the exception to our callers. The code is both correct and clear.

Irritating APIs

Some APIs force us to use more try-catches that we’d like. An example in Java is how to read data from a database using JDBC:

PreparedStatement statement = connection.prepareStatement("...");
try {
    ResultSet results = statement.executeQuery();
    try {
        while (results.next()) {
            // ...
        }
    } finally {
        results.close();
    }
} finally {
    statement.close();
} 

Here the problem lies in how the JDBC API is defined. We can’t change it of course, but we should encapsulate all uses of the JDBC API in a single class, so that we don’t have to look at this code anymore. Treat that class as your adapter to JDBC. For instance:

Results results = new Database(connection).read("select * from foo");
  // use results

Of course our object is a lot less flexible than the JDBC API. This is expected: we want to decide how we use JDBC and encapsulate that “how” in a single place.

How to host a JavaScript coding dojo

June 27th, 2013

Yesterday I organized a JavaScript coding dojo for my current customer’s programmers. Here’s what we did. Disclaimer: I’m not a JavaScript ninja, nor were most of the dojo participants. We need to keep it simple. We also need to make it fit within two hours.

I wanted the exercise to have a user interface. Why? Because we did many domain-only dojos, and I think we’re missing something. The UI is important: it makes the exercise more fun, and it teaches you lots. So, where to start? My starting point is the principle of domain-view separation. We want an extremely dumb UI that calls to the domain logic whenever it needs something.

My other point is that I don’t want to test the UI. We don’t have time to setup something like Selenium, and since we don’t know much JavaScript we would waste a lot of time. So we write a small UI, without tests, checking how it looks in the browser at every step. This is important: we don’t have the tests, but we have the browser to give us high-quality feedback. Also remember to keep the JavaScript console open when you do this.

The starting setup

We start from an empty exercise setup, that contains four files (not counting library files). For exercise “foo”, we have:

  • foo.html is the UI
  • foo.js contains the logic
  • foo_test.html is the test runner
  • foo_test.js contains the tests

The starting foo.html looks like this:

  
<html>
  <head>
    <title>FOO</title>    
  </head>
  <body>
    <h1>Foo!</h1>
    <script src="lib/jquery.min.js"></script>
    <script src="foo.js"></script>
    <script>
      $(document).ready(function() {
        console.log("hello");
      });
    </script>
  </body>
</html>

The starting foo.js is empty. The test runner is

<html>
  <head>
    <title>Foo Test</title>
    <link rel="stylesheet" href="lib/qunit.css">
  </head>
  <body>
    <div id="qunit"></div>
    <div id="qunit-fixture"></div>
    <script src="lib/jquery.min.js"></script>
    <script src="lib/qunit.js"></script>
    <script src="foo.js"></script>
    <script src="foo_test.js"></script>
  </body>
</html>  

and foo_test.js is simply

module("Foo");

test("it works", function() {
  equal(false, true);
});  

As you can see, I setup jQuery and QUnit. These are our tools.

The demo

The dojo agenda is:

  1. Introduction and demo. I solve a simpler exercise in front of the audience, with a video beamer.
  2. Explain the problem to be solved.
  3. Someone in the audience builds the UI and the first broken test.
  4. Someone else passes the test, and demonstrates that it works in the browser too! Watch out for when the tests are green and the UI is broken :) Then this person writes the next broken test.
  5. And repeat the last step until finished.
  6. Retrospective

My demo exercise was “write an application that allows me to enter a number, and prints that number doubled. Let’s call it Doubler“. The UI I built was

<html>
  <head>
    <title>doubler</title>    
  </head>
  <body>
    <h1>doubler!</h1>

    <p id="display"></p>
    <p><input type="text" name="number" value="" id="number"/></p>

    <script src="lib/jquery.min.js"></script>
    <script src="doubler.js"></script>
    <script>
      $(document).ready(function() {
        var $number = $("#number");
        var $display = $("#display");
        $number.change(function() {
          $display.html("The input is changed and its value is " + 
            $number.val());
        });
      });
    </script>
  </body>
</html>  

When I have this working I can start the TDD process. I know that all I need to do is to replace the hard-coded expression “The input … ” with a call to a domain object, like

  $display.html(new Doubler().process($number.val()));

Now I have the power of TDD at my disposal. I can make Doubler do what I want, and I know it will work in the UI. And Doubler is completely unaware that there is a UI at all; all it has to do is implement the pure domain logic. At this point, I also show how to implement an object (in the sense of object-oriented programming) in JavaScript. There are a few hundreds different ways to do that; the style I used is like this:

function Counter() {
  var itsValue = 0;
  this.increment = function() {
    itsValue++;
  }
  this.value = function() {
    return itsValue;
  }
}  

The “itsValue” local variable is accessible to the two methods (since they are closures), but is completely incapsulated and inaccessible from the outside. A test for this object could be

  test("It increments its value", function() {
    var counter = new Counter();
    counter.increment();
    counter.increment();
    equal(counter.value(), 2);
  });

After this, I proposed the team to solve stage 1 of the Tic-Tac-Toe Application Kata by Ralph Westphal. It’s simple enough to be finished in a hour, yet not trivial. One point to watch out for: we want the Game object to contain the state of the game. We don’t want to rely on the UI to tell the domain object what is the state of a given cell.

If you want a harder challenge, you could implement the Game of Life :)

Discussion

It took me a few test trials to arrive at this dojo format. I experimented with an explicit model-view-controller architecture, where you TDD also the “glue” code that I write in the UI file. This can be done by using html fixtures in the test code. But it didn’t give me the right feelings; it felt unpleasant to work with.

One thing that I surely want to avoid is the approach shown in chapter 15 “TDD and DOM Manipulation” of the (otherwise useful) Test Driven JavaScript development book. The approach in that chapter is to decide a design upfront, such as MVC, and then unit test that the controller connects itself in a certain way to the view and the model. Why I don’t like it? Because the design does not emerge from a test. Because it’s testing the implementation, not the specification. Because I want my first test to be about the valuable logic of the problem, not about a technical detail. Because I want every test to be about a valuable business behaviour.

The format I came up with feels right to me. It’s appropriate for beginners. I’m not sure that you would want to work always this way when you do production work, but it certainly is a good starting point.

Have fun!

A fundamental design move

May 30th, 2013

Pardon me if the content of this post looks obvious to you. It took me years to understand this!

When doing incremental design, I found that there is one fundamental move that makes design emerge. It is

  1. I recognize that one thing has more than one responsibility;
  2. then I separate the responsibilities by splitting the thing into two or more smaller things;
  3. and I connect the smaller things with the proper degree of coupling.

For instance, in the description of the domain of the game Monopoly we have this sentence:

A player takes a turn by rolling two dice and moving around the board accordingly.

A straightforward translation of this into code is

class Player {
  // ...
  public void takeTurn() {
    int result = Math.random(6) + Math.random(6);
    this.position = (this.position + result) % 40;
  }      
}

Can you see that Player#takeTurn() does two things? You can see this from the beginning by the wording: “by rolling two dice *and* moving around the board”.

You can also see it when you try to write the test:

@Test public void playerTakesTurn() {
  Player player = new Player();
  assertEquals(0, player.position()); // initial position
  
  player.takeTurn();
  assertEquals(???, player.position()); // how should I know???
}

We can’t write the last assertion because we have no control over the dice.

The standard way to solve this is to move the responsibility of extracting a random result to a separate class.

@Test public void playerTakesTurn() {
  Dice dice = new Dice();
  Player player = new Player(dice);
  //...
}

class Player {
  public void takeTurn() {
    int result = this.dice.roll();
    this.position = (this.position + result) % 40;
  }      
}

This still does not solve our problem, since Dice#roll() will still produce a random result that we have no control over. But now we have the option of making the coupling between Player and Dice weaker, by making Dice an interface and passing a fake Dice implementation that will return the result that we want:

@Test public void playerTakesTurn() {
  Dice dice = new FakeDiceReturning(7);
  Player player = new Player(dice);
  assertEquals(0, player.position()); // initial position

  player.takeTurn();
  assertEquals(7, player.position()); // now it's easy
}

This design move, that is almost forced by the need to write a clear test, has a number of advantages:

  • Now we have the option to pass different dice implementation. If the rules ever called for using different kinds of dice (for instance, 8-sided dice) we would not need to change the Player class at all.
  • Now we can test the Dice implementation separately. We might thus discover the bug in the above random number generation code. (did you see it?) :-)

So, to summarize, the fundamental design move is in three steps:

  1. You realize a portion of code has two responsibilities, perhaps because the test is hard to write.
  2. You separate the portion of code in two parts; this is usually some form of “extract method“.
  3. You’re not finished yet, because you still have to decide what kind of coupling you want between the two parts. Usually, a simple extract method will produce a coupling that is too tight. More work is required to ease the coupling to the degree that you want.

It is simply a consequence of the Single Responsibility Principle; but it can also be seen as the or as the application of the “clarity of intent” rule in Kent Beck’s 4 Rules of Simple Design.

Now the interesting thing is that this design move applies not just to methods, but to classes, modules, services and applications! Whenever you see two things inside one, separate them. If you applied the right degree of coupling, you will end up with a system that is simpler.

Roles, stereotypes, kinds of objects

May 10th, 2013

I’ve been thinking lately about the ways that different authors explain OOP. I’ve drawn a little diagram that I would like to share with you.

The sources for this are, in no particular order:

Each of these authors has a perspective I find useful. I would love it if there was a comprehensive, single model, but so far I can’t see how to systematize them.

It gets weirder when you start collecting design principles… I might do a mind map of those some day. Somehow I can see how SOLID and GRASP (for instance) are compatible. They are pointing in the same general direction, but from different angles.

Doing the job of the customer?

March 24th, 2013

Summary: I spoke about how XP is about having a productive conversation with the customer, to help them learn about what they really need, using working software as a focus. One reaction was “why should we do the job of the customer, when they *should* know what they want?” My answer is that they can’t possibly know what they want right from the start; learning what is really needed is a process. We do it because it’s the job of software development to make this process happen.

Lo scorso venerdì ho fatto una presentazione su Extreme Programming al Codemotion. Ho parlato di come i metodi agili abbiano al centro la conversazione fra sviluppatori e clienti; una conversazione che permette ai clienti di scoprire quello di cui hanno veramente bisogno, grazie anche al prodotto che viene sviluppato iterativamente e permette di aggiustare il tiro ad ogni iterazione.

Una reazione è stata: “Perché dobbiamo fare noi il lavoro del cliente? Perché facciamo tutto questo per il cliente quando negli altri campi dell’ingegneria non si fa?”

La mia risposta è che non sono convinto che negli altri campi dell’ingegneria sia poi così diverso da quello che si fa nel software, e comunque se anche fosse non mi interessa. Quello che mi importa è che il cliente *non ha altra maniera* di scoprire quello che gli serve veramente se non attraverso una conversazione focalizzata su un prodotto sviluppato in iterazioni successive. Per cui noi questo facciamo: la ragione per cui sviluppiamo software è per soddisfare i bisogni del nostro cliente.

Se potessimo ottenere lo stesso risultato applicando qualche formula o processo che non richieda tutto questo impegno da parte di tutti, lo faremmo. Ma non c’è! Questo è il semplice dato di fatto.

Il nostro business, nello sviluppo software, consiste nel fare felici i clienti… non lo percepisco come un problema. E’ impegnativo, d’accordo, ma è giusto così.

Refactor to remove duplication

March 17th, 2013

The gist of the message I got from Extreme Programming in the early years of this century was that good code would just emerge if we followed the four rules of Simple Design, as advocated by Kent Beck:

The code is simple enough when it:

  1. Runs all the tests
  2. Has no duplicated logic
  3. States every intention important to the programmers
  4. Has the fewest possible classes and methods

in this order.

Various formulation of this list exist. Given that “Runs all the test” is granted (we don’t want broken code) and “Has the fewest possible classes and methods” is also granted (simplicity seems to imply “few things”), I often wondered how the other two rules can be used to generate good design.

J.B. Rainsberger says:

Put more simply, if you master removing duplication and fixing bad names, then I claim you master object-oriented design

That’s a bold claim! How can this be?

In TDD By Example, Kent Beck says that the third step of TDD is not just “refactor”, but refactor to remove duplication. The point then is “what is duplication?” Is that just duplicated lines of code?

Over time I started collecting interesting examples of duplication. It turns out that seeing duplication is a skill that has to be learned.

Obvious duplication

The most obvious form of duplication is duplicated lines of code. That is usually cured by extracting the common lines in a method. The extraction of a method is often followed by moving the method to a new class, or another existing class.

This is just one way the four rules push towards a better design. There are others.

Duplication in names

There is a beautiful simple exercise in chapter 1 of Essential Skills for Agile Development. It asks to remove duplication in code that looks like this one:

class Organization {
  String primaryContactFirstName;
  String primaryContactLastName;
  String primaryContactPhone;
  String secondaryContactFirstName;
  String secondaryContactLastName;
  String secondaryContactPhone;
  ...
}    

There is no “code” here, just data declarations. There is quite obvious duplication in the names though. The string “primaryContact” is repeated three times. The sequence “firstName, lastName, phone” is repeated two times. The point is to arrive at something like

class Organization {
  Contact primaryContact;
  Contact secondaryContact;
  ...
}    

Primitive obsession

Primitive Obsession is one of the classic smells from the Refactoring book. It happens when we use primitive types in place of our own types. You can see it in the Organization example above, where we use a String to represent a phone number, and again String to represent names of persons.

Primitive Obsession is one of the most common smells. Most developers are not even aware that it is a problem. It is also a smell that takes a long time to remove. And … it is a form of duplication. We are duplicating the choice of representation for a concept. We can see the cost of this choice when we decide that, say, we want to stop using Java native Date type and start using the Joda Time replacement; then it takes ages to convert all of our code to the new type.

But when we do this replacement, we are still falling in the same trap; if we change our mind again, it will again take a very long time to convert the code. What is the answer to this problem? Should we think long and hard before we start our project on which Date class we want to use, to minimize the chance of having to change it later? Would that work?

Of course not! What we really want is to be able to change our mind quickly, whenever we learn that our first choice was not adequate. Again, the key is in removing the duplication: make the choice in a single place; all of our code will use our own XDate class. Our XDate could use java.util.Date internally, or something else, but code outside XDate does not know and does not care.

(Aside. Using our own Date type has the beneficial effect that all the static method that are usually found in a number of DateUtils classes become instance methods in XDate. Another smell is removed! End Aside.)

Using third party APIs directly

The primitive obsession smell is just an example of a more general problem: when we use someone else’s API, we use it directly throughout our code. When we need, say, to download a data file from some service, what do we do? Do we start littering our code with calls to java.net.URL and java.net.HttpUrlConnection? Heavens, no! That would be committing ourselves to a particular way to solve the http connection problem, and duplicating it in all the places where we need to do it.

That would also be a violation of what Robert Martin calls the “Dependency Inversion Principle”: depend on abstractions, not on concretions. The java.net.URL is a concrete way to solve the “download a remote file” problem.

A better solution would be to hide the decision inside a class. Just define a RemoteFile class with a download method. This way we avoid duplication.

Alas, this is another smell that most developers don’t even know about.

Hiding design decisions

This brings us to a connection that was not obvious: removing duplication leads to the famous paper by David Parnas On the criteria to be used in decomposing systems into modules. Quote:

We propose instead that one begins with a list of difficult design decisions or design decisions which are likely to change. Each module is then designed to hide such a decision from the others. Since, in most cases, design decisions transcend time of execution, modules will not correspond to steps in the processing.

There you have it: a class is a way to codify and centralize a design decision. A design decision that is duplicated should be moved to its proper home in a single place. This is one of the things that an XPer must learn, in order to become effective at becoming faster than the customer :-)

Further reading: an essay by James Shore on why removing duplication is key to making continuous design work: it mitigates the risk that unforeseen circumstances will force us to change an earlier decision.

Another personal update

February 22nd, 2013

Almost one year ago I started again as an independent consultant, after five years in Sourcesense/XPeppers. How’s it going?

I have worked with great customers. They are all good places to work, both technically and from the point of view of the fundamental values: first of all, respect. (If you’re a good Java, C#, Php or Ruby programmer and you could be interested in working for one, just ask me.)

What value do I bring to these customers? What kind of work do I do?

When I do my best work, I look for the biggest problem and keep working on it, trying different solutions until it gets better (a simple recipe that I learned from Pascal.) It’s not always clear what the biggest problem is, but mostly I look for things that are out of sync with what an Agile team should do. Two chief things to look for:

  1. How often do we ship?
  2. Are the customers (business owners, CEO, other stakeholders) happy? (Which requires sometimes to have difficult conversations)

Actually, I don’t really invent or apply the solutions myself; I try to get the organization’s people to do that. This makes it far more likely that the solutions make sense and work :-)

I’ve been fairly busy, and this is why I didn’t write here for a long time. Right now I’m happy with the way it’s going.

TDD no mundo real

February 22nd, 2013

TL;DR Mauricio Aniche‘s TDD No Mundo Real is a very good introduction to TDD.

I learned about Mauricio Aniche’s book on the Growing Object-Oriented Software mailing list. At first I thought I would have to wait for a translation, as I don’t speak Portuguese. But I soon discovered that I can follow the meaning well enough; in a few spots I got help from Google translate. I imagine that any speaker of Latin languages can read this book; just try!

This book is a modern introduction to TDD. The thing I like the most about it is that it explains the fundamentals using very simple examples. This for me is high praise: explaining things in a simple way is not easy. And it’s always worth it to work on the fundamentals, even when you think you’re an expert.

Chapters 1 to 3 are introductory. Here Mauricio writes for someone who does not know anything about TDD; he explains how it works and why it’s much better than traditional development techniques, such as writing little “main” methods to test Java classes.

Chapter 4 is about “Simplicity and baby steps”. This is a fundamental point about TDD, that you work in small increments. One good point that Mauricio makes is that this concept is often misunderstood. Some programmers take “the simplest thing that could possibly work” to mean “I’ll do the simplest possible modification to the current code.” This is wrong! It really means “make the code as simple as possible with respect to the current tests.” Sometimes this means making big, sweeping refactorings in order to make the system simpler.

In chapter 5, Mauricio talks about TDD seen as a design technique. Most TDD practicioners agree that TDD is more about design than tests; yet not everyone can explain well how is it that TDD helps you to design. The book gives a few examples of how the feedback provided by tests gives you an indication that the production code should be changed.

“Quality of test code” is the subject of chapter 6. Here we learn how to keep our tests DRY by using Setup and Teardown.

In chapters 7 and 8 Mauricio shows how tests alert us that the production code has problems of cohesion or coupling. This is probably the part that even old hands at TDD will find most interesting.

Then chapter 9 explains some fundamental things about encapsulation, “Tell, don’t ask” and the Law of Demeter.

Chapter 10 is an explanation of integration tests.

In conclusion, this book is a concise and complete introduction to TDD. It’s very simple and addresses the kind of problems that most working programmers, expecially those working in business software, are likely to find. What are its shorcomings? I can think of two: it’s not available in English, and there’s no treatment of scenarios, acceptance tests, breaking down features in a list of test.

Let’s just hope that Mauricio will translate his book to English, so that it can be circulated more widely.