Use Full Words for concepts, not codes or abbreviations. This is the fifth in a series of posts on Code Gardening - the practice of making small improvements as you see them while you are working.

Contractions cloud understanding and slow down anyone reading the code. The exception is for extremely well-known abbreviations and contractions such as Xml and Html.

Consider this fragment of code:

public TimeSeries FindByClassifiction(string clssfctn)
{
    using (var rep = new TimeSeriesRepository())
    {
        using (var tns = rep.StartTransaction())
        {
            var rslt = rep.FindByClassification(clssfctn);
            tns.Commit();
            return rslt;
        }
    }
}

This code is full of contractions and codes that require deciphering by the reader.

Some of these are relatively easy to work out … rep must mean repository, tns must mean transaction and rslt might mean result.

But classfctn is a bit of a mystery. Does that stand for classifiction - a ke word from the method name. And what is a classifiction anyway?

Contrast the code above with this cleaned up version …

public TimeSeries FindByClassification(string classification)
{
    using (var repository = new TimeSeriesRepository())
    {
        using (var transaction = repository.StartTransaction())
        {
            var result = repository.FindByClassification(classification);
            transaction.Commit();
            return result;
        }
    }
}

No more cryptic codes to decipher - not only is the code much easier to read, we can now see that we’re finding Classifications.

Prior post in this series:
Intention Revealing Method Names
Next post in this series:
Document Every Member

Comments

blog comments powered by Disqus