There is a single technique to get inside your users’ requirements that isn’t used often enough: become an user. Are you writing a system for the help desk? Spend a couple of days monitoring the phones with an experienced support person. Are you automating a manual stock control system? Work in the warehouse for a week. As well as giving you insight into how the system will really be used, you’d be amazed at how the request May I sit in for a week while you do your job? helps build trust and establishes a basis for communication with your users.

(…)

The requirements mining process is also the time to start to build a rapport with your user base, learning their expectations and hopes for the system you are building.

From The Pragmatic Programmer, by Andy Hunt & David Thomas.

Although I have had few opportunities to practice such technique, I strongly believe invest some time with the actual user can be way better than spend lots of hours in verbose and boring meetings with managers.

The more conditional blocks an algorithm has, the greater is its cyclomatic complexity, which means the number of possible paths that algorithm can follow. Then, when you’re reading and understanding a piece of code, everytime you face an if statement, you have to save the current flow in your mental stack and then start to read the conditional block till its end in order to figure out what that block is about. The bad news is that, as my friend Filipe Sabella says, unfortunately, you can store no more than seven things in your mental stack. Let’s take a look at the following code:

var guess = function(letter) {
  if(hiddenWord.reveal(letter)) {
    hiddenWord.render();
    if(hiddenWord.isEverythingRevealed()) {
      alert('You Kick Asses!');
      nextLevel();
    }
  }
  else {
    image.showNext();
    if(--chances == 0) {
      alert('Looooser!');
      gameOver();
    }
  }
};

The above Javascript function implements a guessing procedure in a Hangman game. You probably didn’t figure it out before to finish reading the entire code. That’s because you had to understand the implementation details in order to figure out the intention behind each conditional block. In the end of this process, you have probably named those blocks implicitly in your mind.

Now, let’s take the more external if/else blocks and give them names according to the intention behind them. Thinking about the Hangman game, when the player guess a letter, two things can happen:

• If the hidden word has that letter, he did a hit;
• Otherwise, he did a mistake.

So, let’s say the same thing using Javascript language instead of English:

var guess = function(letter) {
  if(hiddenWord.reveal(letter))
    hit();
  else
    mistake();
};

var hit = function() {
  hiddenWord.render();
  if(hiddenWord.isEverythingRevealed()) {
    alert('You Kick Asses!');
    nextLevel();
  }
};

var mistake = function() {
  image.showNext();
  if(--chances == 0) {
    alert('Looooser!');
    gameOver();
  }
};

The new version of the guess function has explicit names for each alternative computation. We can now read and understand it more quickly, in a single flow, without to store things in our mental stack. Observe that in this new version, the reader get the intention before to enter in the implementation details (actually, we don’t even need to know the implementation at this point).

We can go further and use the Javascript ternary conditional operator to make the guess function more straightforward.

var guess = function(letter) {
  hiddenWord.reveal(letter) ? hit() : mistake();
};

Pretty simple, don’t you think?

We can also keep going on this process and apply the same technique on the hit and mistake functions. So, let’s take the conditional blocks inside these functions and think about their underlying intentions in order to be able to give them proper names:

• The hit function has a conditional block describing the behaviour the game should follow when the player wins the match;
• The mistake function has a conditional block describing the behaviour the game should follow when the player has no more chances and then loses the game.

Using those names to represent the conditional blocks, we gonna achieve the following result:

var guess = function(letter) {
  hiddenWord.reveal(letter) ? hit() : mistake();
};

var hit = function() {
  hiddenWord.render();
  if(hiddenWord.isEverythingRevealed())
    win();
};

var mistake = function() {
  image.showNext();
  if(--chances == 0)
    lose();
};

var win = function() {
  alert('You Kick Asses!');
  nextLevel();
};

var lose = function() {
  alert('Looooser!');
  gameOver();
};

Now, as you can see, the whole code has only one-line ifs, and the intention behind each conditional path is explicitly named. As well as giving a better reading, we have improved the maintenance by giving a very clear place for each chunk of work. For instance, if you need to change the win behaviour, you just go directly to the win function and do your changes.

Conclusion

I believe that by using one-line ifs you can make your code more literate and descriptive, allowing readers get the overall picture at first and get deeper in details only if they need. Compare the above version of the whole code with the first single guess function. Note that in the last version the reading flows more naturally, as if the code was telling you a story.

Moreover, this approach makes software development cheaper and programmers more productive. Given that the major cost is software development is the maintenance, reading and understanding code in a more effective way could give you significative financial improvements.

Finally, an additional award one-line ifs give us which I love is, for languages based on C syntax (like Java, Javascript, and C#), you don’t need to use curly braces. As well as helping to reduce the syntax noise (and give your code a Python flavour), it also makes the code more aesthetic and comfortable to the reader eyes.

Knowing about computer languages and language technology such as ANTLR will make your coding life much easier. Don’t be afraid to build a human-readable configuration file (I implore everyone to please stop using XML as a human interface!) or to build domain specific languages to make yourself more efficient. Designing new languages, when appropriate, is the hallmark of a sophisticated developer.

Terence Parr, in his ANTLR book.

To develop an external DSL can be fun if you have a great tool like ANTLR in hands.

Se se observa a evolução que a educação dos indivíduos segue, nota-se, nas escolas primárias, a ação de governar como sendo a mais forte; e nas escolas de um nível mais elevado, vê-se a ação de governar as crianças diminuir sempre de intensidade, enquanto o ensino representa um papel cada vez mais importante. Aconteceu o mesmo com a educação da sociedade. A ação militar, isto é, feudal (governamental), teve de ser mais forte em sua origem; e o poder administrativo deve necessariamente acabar por dominar o poder militar.

(…)

Em conseqüência de uma revolução que aboliu o sistema feudal, a sociedade exige se desenvolver, harmonizar suas potências econômicas; desde este momento torna-se inevitável que o governo, negado em teoria, se destrua progressivamente na prática.

Proudhon, em seu excelente livro A Propiedade é um Roubo.

Em lugar de um milhão de leis, uma única é suficiente: não faça a outro o que vós não quereis que vos faça; faça a outro como desejais que vos seja feito. Mas é evidente que isto não é uma lei; é a fórmula elementar da justiça, a regra de todas as convenções. A simplificação legislativa nos reconduz à idéia de contrato, conseqüentemente, à negação da autoridade. Efetivamente, e a lei é única, se ela resolve todas as antinomias da sociedade, se ela é consentida e votada por todo mundo, ela é adequada ao contrato social. Ao promulgá-la, vós proclamais o fim do governo. O que vos impede de aplicar esta simplificação imediatamente?

How do you provide global variables in languages without global variables? Don’t. Your programs will thank you for taking the time about design instead.

Beck, in Test-Driven Development By Example.