We have recently introduced two defects, while trying to improve old, obscure code. Of course we are to blame for not being more paranoid and not researching more why the code was there. But if the code was clear to start with, if it followed the least astonishment principle, the errors wouldn’t have happened. In both cases the original code provoked the “WTF?!” reaction in the reader.
Martin Fowler’s Refactoring to an Adaptive Model, 11/2015 – replacing imperative logic with a declarative one, with rules encoded in JSON so that they can easily be shared across platforms and updated without re-installation. A few other nice refactoring points too.
Most of our software logic is written in our programming languages, these give us the best environment to write and evolve such logic. But there are circumstances when it’s useful to move that logic into a data structure that our imperative code can interpret – what I refer to as an adaptive model. Here I’ll show some product selection logic in JavaScript and show how it can be refactored to a simple production rule system encoded in JSON. This JSON data allows us to share this selection logic between devices using different programming languages and to update this logic without updating the code on these devices.
Today’s lesson: Delegate the hard work orthogonal to your business logic – concurrency, asynchronicity, state maintenance during iteration etc. – to your language and API if you can. They are more likely to get it right and your code will be more focused on what you are actually trying to do. You should feel an unpleasant tingling when you have do these manually. We will look at JavaScript code that uses asynchronous calls to get data in a too manual (and incorrect) way and improve it to delegate the necessary synchronisation to the promises library Q that it already uses.
Today we will discuss a conflict between the design values of keeping things simple, stupid (KISS) and robustness, between underdesign and overdesign.
We were writing a batch Java application and needed to ensure that at maximum one instance is running at a time on the server. A team member had the good idea of using lock files, which indeed worked and helped us a lot. However the original implementation wasn’t very robust, which has cost us valuable people time and expensive context switches due to troubleshooting the damn application rejecting to run and locating the lock file.
As Øyvind Bakksjø of Comoyo has recently explained, a software engineer is distinguished from a mere coder by thinking and caring not only the happy path through the code but also about the unhappy cases. Good engineers think about possible problems and try to handle them gracefuly so that code that depends on them and their users have easier time dealing with problematic situation. Robustness includes catching errors early, handling them in a good way, and providing useful and helpful error messages. On the other hand, simplicity [TBD: Hickey] is a crucial characteristic of systems. It is always too easy to spend too much time on making code bullet-proof instead of focusing the effort somewhere where it would be more valuable to the business.
It is not always clear which code is better or worse as it might depend on the needs and the team in question. Let’s have a look at two different implementations of a database-backed Set, one that is straightforward and easy to understand and another one that has more structure and less duplication at the expense of understandability. Which one would you choose?
“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.
We have here a Python API for fetching data from Mongo and either returning the raw JSON or a formatted, “parsed,” one. There is certainly a number of things that could be improved (it has been written by a non-programmer and no Python expert, so it is actually a real achievement for him) but what I want to focus on is the API exposed to the clients.
It troubles me because the API exposes too many details about its inner workings and forces the clients to know them.
Wonders of Code 