My last post discussed techniques I once saw as the height of cleverness but now deem foolish. The truth is: I’m still battling with these coding dilemmas everyday… It seems to be a constant game of cleverness/terseness/speed vs. verbosity/readability.
We’re told to write code for the poor soul who has to maintain it in the future. What nobody tells you is how much knowledge this poor soul has, both about the language and the problem domain. People also say to expect this future maintainer to be an idiot — this will mean you write the most understandable code possible. But again: how much of an idiot is this person?
The fact is: we have a set of unspoken assumptions we tend to make about this mystery future maintainer.
Level 1 maintainer
- Sentient humanoid
- Speaks/Writes English well
- Has programmed before
Level 2 maintainer
- Knows the correct syntax for if, else, for, while, do, throw, function, var …
- Knows about types
- Knows all the types available in JS
- Knows the difference between a statement and an expression
Level 3 maintainer
- Knows about strict vs. non-strict equality operators
- Knows about short-circuiting in logical operators
- Knows the difference between Arrays and array-like Objects
- Knows several ways to cast a value, and ways to implicitly force coercion
- Knows regular expressions to an intermediate level (anchors, alternation, character classes)
Level 4 maintainer
- Knows what a bitwise operator does
- Knows about primitives vs. objects, and wrapped primitives for method calling
- Knows what a closure is
- Knows how properties are resolved via the prototype chain
- Knows the differences between prefix and postfix increment operators
- Knows about variable/function-declaration hoisting
- Knows the exact difference between x==null and x===null
- Knows the difference between function declarations and function expressions
Level 5 maintainer
- Knows how to check types without using typeof or instanceof
- Knows why
new Number(1) != new Number(1)
- Knows regular expressions well (lookarounds, capture vs. no-capture, greed)
- Knows what named function expressions are
Level 6 maintainer (Eich level)
- Knows all precedence and associativity of all operators
- Knows where ASI will put semi-colons
- Knows the subtle differences between ES 3.1, 5.1 and 6th Edition draft
*** The above is not exhaustive and is very subjective. I don’t wish to compartmentalize understanding into levels — it’s misleading. I just wanted to somehow portray these assumptions in a clearly understandable way.
I think most devs simply do not consider a future maintainer that is any less capable than themselves, and perhaps this is a problem. If you mark yourself as a maintainer 4.5 then is it fair for you to write in a way that presumes that all future readers of your code are <= 4.5? Is this reasonable?
I suppose it depends on what the code does (e.g. high level MVC sugar vs. low-level 3D rendering) and the people that you’re currently working with, for it is from them that you are likely to draw your estimation of an appropriate maintainer level.
I’m interested to hear other peoples’ opinions on this.
What level do you assume in your future maintainers? How clever does your code get before you deem it reasonable to add a comment or opt for a more explicit and clearer technique?