Concise code: brevity and clarity

Posted on 20. Jun, 2011 by Guilherme Silveira in agile, design

A few years ago, with the wave of new (and old) languages growing its acceptance rate in the market, some people appeared defending code with the intention of being “concise”.

Being concise means express a lot, with a few words; being clare and sucint; brief, but with all the required information; having characteristics of brevity and clarity. Note how all definitions imply in being brief, but also about the clarity of the information. Those are two fundamental factors for searching high quality code, easy to be maintained in the long run, affecting the project’s maintainability as much as its architecture does.

Let’s take the act of saving an user in the only database accessed by the application as an example:

user.saveInTheDatabase(database)

It’s clear, it’s even redundant once the name of the method is “typified” whilst repeating the word database. The following code keeps the same clearness related to the same responsibility, but its also succint:

user.save

In another situation, the same code presented above might be implemented by executing other tasks, such as inserting objects related to the user in somewhere else:

def save
  super
  machines_to_install.each do |instance|
    create_machine(instance)
  end

  # or any other effect, collateral or returned
end

The same code is still succinct, but not clear:

user.save

In fact, it lies. It does not say what it will actually do. The search for the “shortest” possible code introduced the possibility of misreading, misinterpreting, even worse, the name of the method induces the error: the code is not concise, it’s just brief.

For this reason, some advanced techniques, such as AOP or even reflection, should be used with care when dealing with domain code. Transparent remotability, EJBs, JPA, ActiveResource, ActiveRecord and any other libraries that work with a layer that it tries to obfuscate might generate problems if the end developer does not fully understands whats beyond it – and the developer who just joined the company *does not*. This is the case where multiple remote invocations or N+1 sql queries, which the mentioned frameworks might induce if not used properly.

Concise does not mean a brief text. One of the biggest challenges of an author is to be concise, trying not to bore his readers, keeping the text’s clarity. Some languages or even libraries might speed up or down the process to say something in a few words, which does not mean the code will be easier to understand and, consequently, to maintain in the long run.

Writing less – the lines of code metric – brings the shortest code, but not necessarily the clearest or best. In the following example, is the client just being saved or is there something else going on, and this “pseudo-conciseness” is tricking us?

cliente.save()

Tags: agile, code, design, quality