Geeks With Blogs

Dev.Hell Harrowing the tech business like it's 1999
I have written a couple of essays that I haven't posted yet talking about some design fallacies, but it occurs to me that I should probably talk about what actually counts as good design first. So let me do just that.

-ities of the Plains
Good design of course produces code with all the virtues we casually espouse. Most of these are end with the suffix -ity: maintainability, extensibility, scalability, reusability, readbility. I've been in this business for 17 years now and the longer I spend the more convinced I am that the absolute most important number one feature of good design is clarity

Ask yourself, is it clear what this code does? 

I don't mean that the code is commented or documented. These things are helpful, of course, and if you find yourself in an environment I bid you beware of the Queen of Hearts. Comments and documentation are lovely things, where they exist, but code should be clear enough that they are not required.

Clarity implies that the code is code is concise and elegant. That means that it does the job it was designed for, and nothing else. Clarity implies that the codebase has nothing to hide. 

What's the Algorithm?
Most business software has a purpose beyond the management of data. Usually this is a set of algorithms or calculations that provide some value proposition to customers.Some examples from my own career include the calculation of depreciation; the rendering of a Triangulated Irregular Network; the decision about which financial assets to trade or the figuring how many software licenses have been consumed. 

These areas of the codebase are invariably difficult. However beautifully the software has been architected, complex algorithms require complex code solutions...

...and that makes it even more essential that the code you write in these areas is clear. 

No matter how complex the algorithm there should be a logical way for a new engineer to look at it and discover what it does. Steps should be clearly labeled. Flow of control should be obvious. Methods should be small and scrupulously well-named. The goal is to be able to read the algorithm directly out of the code.

The Name Game
Is there a mathematical formula invoked? Make sure the name of it appears in the code, and that its terms are named recognizably. If it's Einstein's formula for mass-energy equivalence, call it that, and make sure the terms are E, m and c. Are you implementing a sorting algorithm? If it's a mergsort, make sure you call it 'mergesort'. 

If part of the algorithm needs to be implemented in another language, make it clear what's happening and the reason for it it. If you're firing up a stored procedure, or you're threading up some asynchronous operations, or forking out to another process or farming a job out to another server. Don't keep them for a surprise that another developer can will enjoy at 5am on the day of go-live.

These algorithms are the crown jewels of your software suite and they need to be treated as such. Because here's the thing: you're not just going to implement them once and forget them. Sooner or later there's going to be a new dimension to consider, a new suite of use-cases, a new set of performance or scalability constraints. If the code is a pit of hackery and deception that is going to make a difficult job excrutiating. 

Change or Die
Even the most well-designed code is going to change over time. You cannot design for every eventuality. The best designs are not the ones that never change; they are the designs that can change with the minimum amount of pain. 

On the flipside, this means choosing design patterns and technologies appropriately. I know you want to try out the newest language keyword, the newest library or extension or paradigm or design pattern, but first ask yourself what it's going to do for the clarity of the code. Does the New Thang allow you to write a method more concisely? Does it make the intention of a statement more obvious? Or does it confuse the issue, hide pertinent information, or obscure the flow of control? 

Stay tuned, Dev Rangers. In the coming posts we're going to take a look at how exceptions handling, Reflection and lambdas can effect the clarity of your code for code or for ill. 
Posted on Tuesday, September 1, 2015 12:17 AM | Back to top

Comments on this post: Clarity

No comments posted yet.
Your comment:
 (will show your gravatar)

Copyright © Jason Franks | Powered by: