We expect some things to be arranged in a particular order.  Take for example the sequence of the English alphabet; A, B, C, D, E, F which is pleasing to the eye.  D, C, A, F, B, E is not.

In a similar way, write initializations and parameters in the same order each time so that it is clear when something has been missed.

In the following example, the order of definition member variables of the DataBean do not match the order in the methods.  What did they miss? It is a mess to read.

Inconsistent ordering

public class DataBean
{
    private boolean stored;

    private String owner;  
    private String name;
    private String key;  
    private String type;
    private BeanProperties properties;
    private HashMap knownValues = new HashMap();

    public DataBean(String type, String owner,  
                    BeanProperties properties,  
                    String key, HashMap knownValues)
    {
        this.stored = false;
        this.properties = properties;
        this.key = key;
        this.knownValues = new HashMap();
        this.knownValues.putAll(knownValues);
        this.type = type;
        this.owner = owner;
    }

    public DataBean(DataBean other)
    {
        key = other.key;
        knownValues = other.knownValues;
        properties = other.properties;
        stored = other.stored;
        owner = other.owner;
        type = other.type;
    }
:

In the above example, the developer forgot to copy one or more of the properties across in the constructors.  But which one?  Because the member variables were initialised in a different order it was easy to miss and hard to find even when the error is known.  

Seeing such poor code raises questions about the competency of the programmer; when given a choice between Order and Anarchy, good programmers always prefer Order.

The fixed example has more consistent ordering so it is clear that no member variables have been missed.

Consistent ordering

public class DataBean
{
    private boolean stored;

    private String owner;
    private String name;
    private String key;  
    private String type;
    private BeanProperties properties;
    private HashMap knownValues = new HashMap();

    public DataBean(String owner,  
                    String name,  
                    String key,  
                    String type,  
                    BeanProperties properties,  
                    HashMap knownValues)
    {
        this.stored = false;
        this.owner = owner;
        this.name = name;
        this.key = key;
        this.type = type;
        this.properties = properties;
        this.knownValues = new HashMap();
        this.knownValues.putAll(knownValues);
    }

    public DataBean(DataBean other)
    {
        stored = other.stored;
        owner = other.owner;
        name = other.name;
        key = other.key;
        type = other.type;
        properties = other.properties;
        knownValues = other.knownValues;
    }
:

The rule also applies to writing code in some kind of logical order.

In the following example, there are two methods that check similar information, but in different order.

public int doStartTag() throws JspException  
{
   if (document.isXhtmlPreferred())
   {
       :
   }
   else if (document.isChtmlPreferred())
   {
       :
   }
   else if (document.isWmlPreferred())
   {
       :
   }
}

public int doEndTag() throws JspException
{
   if (document.isWmlPreferred())
   {
       :
   }
   else if (document.isXhtmlPreferred())
   {
       :
   }
   else if (document.isChtmlPreferred())
   {
       :
   }
}

In the above example, there is no reason to process XHTML first in the doStartTag() method yet process XHTML second in the doEndTag() method.  The reader will waste needless time trying to figure out if there is a secret they need to be aware of before making changes.  

It makes more sense to do them in the same order every time, as below.

public int doStartTag() throws JspException  
{
   if (document.isXhtmlPreferred())
   {
       :
   }
   else if (document.isChtmlPreferred())
   {
       :
   }
   else if (document.isWmlPreferred())
   {
       :
   }
}

public int doEndTag() throws JspException
{
   if (document.isXhtmlPreferred())
   {
       :
   }
   else if (document.isChtmlPreferred())
   {
       :
   }
   else if (document.isWmlPreferred())
   {
       :
   }
}
blog comments powered by Disqus