You may have heard of, or heard lots about, the concept of “Clean Code”. At its heart is the concept of choosing your structure and syntax carefully, to ensure it is readable and maintainable by others. How many times have you cursed a predecessor for things like creating methods called “WhoAmI()” which returns a Boolean? Your code shouldn’t trick people into believing it has a purpose, other than what is suggested by your choice of names and object structure.
Pluralsight has a really nice, and short, introduction to Clean Code, which I can thoroughly recommend.
When starting to work to Clean Code principles, it can be tricky to decide where to draw the line between concise and technically correct, and verbose and self-explanatory. Should every little thing be broken down into its own method? Exactly how long and explanatory should you make a variable name? It’s particularly difficult to switch to this new mind-set if you have come from university and you are new to commercial programming. Coding for your degree usually involves lots of one letter variable names.
One place where it can be difficult to decide on where to draw the clean code line, is chaining methods; such as is commonly done in jQuery.
So here’s my one weird tip: Read your code out loud, as a sentence.
Consider this jQuery:
Is this too much chaining? When reading this line out loud, it reads as:
“For the element called TextBox, set the value to nothing and add CSS class of “error”, then add the CSS class of error to its label too.”
I think most developers could understand that, it parses well. So how can we achieve too much chaining for it to be clean code?
“For the element called TextBox, set the value to nothing and add CSS class of “error”, then add the CSS class of error to its label too, then get the next element and add a CSS class of “normal”, then make it checked, then show it.”
As a verbal or written instruction, this would probably be too much for a human to parse without them manually breaking it up anyway.
In C#, as with jQuery, you can also chain ordinary methods that return values and objects. Again, as with jQuery, only do so if it is easy for a human to parse.
But in C#, you also have the power of LINQ to chain queries. Here you will probably find that you are creating longer queries than you can comfortably speak as a sentence. It’s probably best to think of them as a set of bullet point instructions:
.Select(word => word.Trim())
.Select(word => word.ToUpper())
.Where(word => word.StartsWith(“A”))
.OrderBy(word => word);
Get a list of words:
- Remove trailing and proceeding spaces
- Make them lower case
- Get only the words that start with “k”
- Order the words alphabetically
- Return the result.
We are able to chain a little longer with LINQ, as all of the actions will be done on one collection, and subsequent actions on the result of the preceding action. It really helps here to put each new method on the new line, so it can be read as a list of actions. Carriage returns and white space can be your friend, just as paragraphs will make reading prose easier.