Lifelong Learning

Code Readability - Take 3

In my last blog entry on this topic I made the following bogus statement:

"We knew the thing was a Stack, meaning, it implemented the abstraction of a Stack abstract data type, by reading the implementation, and slowly figuring out, "hey, this looks like a stack", and these operations look like operations we normally do on Stacks." to explain how I translated some foreign code into English.

As a reminder, here again is the foreign code:

public interface Pila {
    void agregar (Object o);
    Object extraer();
    Object verTope();
    boolean estaVacia();
    void Vaciar();
}

And here's the Stack "interpretation"

public interface Stack {
    void push (Object o);
    Object pop ();
    Object getTop();
    boolean isEmpty();
    void empty();
}

The statement is bogus, and someone should have taken me to task for making it, (anyone reading these postings?) because you should not have to figure out the semantics of an interface from its implementation. That's pretty circular reasoning. How do you know the implementation is faithful to the "intent" of the interface, if your understanding of the interface comes from your understanding of the implementation?

I could just as easily have translated the Spanish code into:

public interface Pile {
    void add (Object o);
    Object extract();
    Object seeEnd();
    boolean isEmpty();
    void empty();
}

How would I know what's required of the implementation?

What if I had:

public interface Queue {
    void add (Object o);
    Object extract();
    Object seeEnd();
    boolean isEmpty();
    void empty();
}

How do you tell a Stack, from a Queue from a Foo? The answer, lamentably, points out to a glaring deficiency in the Java interface mechanism: the interface cannot possibly tell you the semantics of the defined operations. In other words, a Java interface is inherently unreadable. Claiming that you've read and understood a Java interface would be a vacuous statement. You have no clue what the intended semantics are.

How would you get a clue about the intended semantics?

That's the topic of the next look. Design By Contract.

Code Readability - Take 2

Last week I had some code that was a little bit obfuscated by using a foreign language for identifiers.

Lets see if we can improve the readability of this "foreign" code.

The interface from last week:

public interface Pila {
    void agregar (Object o);
    Object extraer();
    Object verTope();
    boolean estaVacia();
    void Vaciar();
}

If we just use intent-revealing names, we can re-write it as:

public interface Stack {
    void push (Object o);
    Object pop ();
    Object getTop();
    boolean isEmpty();
    void empty();

}

Aah. That looks much better. Now we know the intent of the programmer. But wait, how did we know that Pila meant Stack? We looked it up in a Spanish-English dictionary? We could do that, but what if we did not realize that this was Spanish? When you meet "foreign" code, the "foreign" language is usually a domain you're not familiar with. This is very contrived just to make that point. I hope everyone sees that. Besides, the code could have been as follows:

public interface Shmark {
    void gork(Object o);
    Object fraz ();
    Object sproogel();
    boolean spregel);
    void froogel();
}

We knew the thing was a Stack, meaning, it implemented the abstraction of a Stack abstract data type, by reading the implementation, and slowly figuring out, "hey, this looks like a stack", and these operations look like operations we normally do on Stacks. This required that 1) we had a mental model of an abstraction that we know as "Stack". 2) We recognized the similarity between our mental model and what the code is trying to do. That is the essence of readability. How close can the developer layout his mental model in such a way that it is easy to see it in the code. Much easier said than done!

But is that enough to understand the interface? Not really. We need to specify the contracts that the interface is to honor. The preconditions and postconditions for every method.

We'll do that in the next take.

Code Readability - Take 1

Is this code readable? If it is not, why not? If it is, tell us what it does. Obviously it is a mixture of English and another language. Knowledge of the other language is not required. Or is it? Can you reason through the code without knowing the other language?

public interface Pila {
    void agregar (Object o);
    Object extraer();
    Object verTope();
    boolean estaVacia();
    void Vaciar();
}

public class PilaLista implements Pila {

    private Object elementoTope;
    private PilaLista restoLista;

    public PilaLista() {
        elementoTope = null;
        restoLista = null;
    }

    public void agregar (Object o) {
        PilaLista pilaNueva = new PilaLista();
        pilaNueva.elementoTope = this.elementoTope;
        pilaNueva.restoLista = this.restoLista;
        restoLista = pilaNueva;
        elementoTope = o;
    }

    public Object extraer() {
        if (estaVacia())
            throw new java.util.NoSuchElementException();
        Object tope = elementoTope;
        if (restoLista == null)
            elementoTope = null;
        else {
            elementoTope = restoLista.elementoTope;
            restoLista = restoLista.restoLista;
        }
        return tope;
    }

    public Object verTope() {
        if (estaVacia())
            throw new java.util.NoSuchElementException();
        return elementoTope;
    }

    public boolean estaVacia() {
        return (elementoTope == null);
    }

    public void Vaciar() {
        elementoTope = null;
    }

}

Application Frameworks - Some Thoughts

If you have smart engineers that know their craft, know industry best practices, and know their business domain, why would you need a framework? If you have looked at this issue, or are now looking at it in search of a framework, could you state, in one word, what is the most important consideration that motivates your desire to have a framework?

You can elaborate further, but that probably requires a good deal of space, so lets try to keep it to the one word, for purposes of a canvassing, and maybe a sentence or two in elaboration.

My one word answer: Consistency

My elaboration: I want designs produced by my team, my group, my department, my company to be, above all consistent, so we can have easier sharing of knowledge, easier transfer of knowledge across teams, easier transfer of skills, easier ways of evaluating and judging quality. Different people will have different notions of what "goodness" means - what attributes of a design make it superior to other designs. A framework gives us a common world view, and a common approach to design and construction, a common solution to a set of problems. So I value consistency most.

What is your answer?

An acceptable answer, of course, is "None". We don't need a framework. Would be interesting to read the elaboration accompanying that answer, though.

Other contending one word answers: standardization, productivity, reliability, uniformity, quality, predictability, simplicity. You can add to the list as many as you like, but please choose just one as your overriding concern.

An issue that always arises, or is there as a context on development projects is issue of the relationship between frameworks and projects. I think the relationship should be just like oxygen to a human being. We need it, we breath it, we have it, we don't spend too much time debating how much we need it, how to obtain it, and which is the best technology to provide it.

By the same token, a framework should be available to the project team just as oxygen is. And it is just as vital for their continuing health, as Oxygen is to living things. They should not have to spend any project time debating or selecting frameworks. A framework should be part of their environment, the infrastructure they rest on. The project team should spend every minute of the project time delivering end value to the customer. They need to think through their business requirements, their domain model, the stories they are required to deliver by when, and have total focus on that task.

A framework, therefore, must be provided by a higher order "provider" than the project's immediate builders. It should be part of the environment, or infrastructure. If you are scientifically inclined, the selection of a framework should have been done through a scientific process, based on broader engineering requirements than the needs of one project. If, on the other hand, you are religiously inclined, a framework should be provided by "God" - whoever the Gods of your environment are.