Master Programmers Tell Stories

Code that tells a story

Code is an artistic medium. To some programmers, it can be like clay or marble in the hands of a sculptor.

Let’s look at an example:

foreach (var invoice in invoiceByCustomerType[CustomerType.Customer].Where(i =>
i.Finalised == true || i.GetTotal() > 0 && i.Status == "FINAL"))

The loop is cycling through a set of customer invoices. We receive much information from this line of code. But do we need it all to aid our understanding? No, probably not.

It’s not hard to get the general idea after a few seconds—it’s a collection of finalised customer invoices. Yet, should it take a few seconds of thinking before we understand a line of code? Wouldn’t it be cool if we knew what was going on instantly? Without having to think about it?

It’s not that these few seconds are particularly wasteful when done once. However, reading code becomes taxing for the human brain when it has to work hard to extract intent all the time. It’s like wading through molasses.

OK, back to a better way of communicating the intent of the finalised invoices. I believe this is an improvement:

foreach (var invoice in GetFinalisedCustomerInvoices(invoiceByCustomerType))

Now isn’t that much clearer? We immediately see that we are dealing with finalised customer invoices.

And if it is possible—it may not be—to express the argument invoiceByCustomerType as a class member or property, we could compress the looping logic to:

foreach (var invoice in FinalisedCustomerInvoices)

With this last attempt, we removed all the noisy detail and are only conveying signal.

Hiding The Detail exposes The Essential.
Less is More.
Great programming communicates intent. Communicate intent – first, foremost and always.

The real cost of software development is not in the original writing—it’s the maintenance of code that costs companies dearly.

I came across a great quote the other day. I think it might have been from Uncle Bob. Here is how I remember it: