Tag Archives: readability

Simple or Complex? Familiar Imperative Code Or Makes-Me-Think Declarative One?

We have had a heated discussion today about the two alternatives of JavaScript code that filters out elements with a different hardwareType (if supplied):

The imperative solution (1) is familiar to all of us and thus easy to grasp. However the declarative solution (2) is not familiar, we have to think about what it does, we need to know that .filter({bundle: {product: {type: filter.hardwareType}}}) keeps only bundles that have the given product.type and that .filter(null) does keep all. Thus (1) is easy to understand, (2) isn’t.

Continue reading

Surfacing Hidden Design: Seeking A Better Alternative To Interrelated Mutable Fields

What is better, a bunch of mutable boolean fields and methods operating on them, or an explicit expression of the individual states and transitions between them? Lets study an example from a simulation of the progression of a multi-stage infection.

1. Design hidden in primitive mutable fields and methods

The following class, with a number of interrelated mutable (public) fields, which I should have completed with methods for transitions between their states, made me really uneasy (a var is a mutable field, val is immutable):

The fields keep the state of the progress of an infection. They depend on each other – f.ex. when sick, the person must also be infected, while when dead, she must not be immune.

The progression of the infection is: healthy -> infected and infectious with the chance of 40% (but not visibly sick yet) -> on day 6 visibly sick -> on day 14 dies with the chance of 25% -> if not dead, becomes immune on day 16 – not visibly sick but still infectious -> healthy on day 18.

The problem I have with keeping the state in a bunch of fields is that there is no explicit expression of these rules and that it opens for defects such as setting sick to true while forgetting to set also infected. It is also hard to understand. You could learn the rules by studying the methods that alter the fields but it requires a lot of effort, it isn’t easy to distinguish between an incidental implementation detail and intentional design and this code does not prevent mistakes like the one described.

Continue reading

Intention Hidden In Implementation And Misty Edge of Validity

The code is the documentation” – except that from poorly written code you cannot tell what is an intrinsic part of the solution and what is an accidental implementation detail. And a piece of code can rarely handle any possible data – yet, without a good documentation or precondition checks, you can’t even guess at what are valid or unexpected inputs. Today we will explore a piece of JavaScript code that both hides the intention in the implementation (the “why” is not clear from the “what” the code does) and operates correctly only under particular but unstated conditions.

Continue reading