Self-documenting code with Warewolf

When learning a new language one of the things I do is implement the first 20 problems of Project Euler. It’s my personal code kata for new languages. It allows me to contrast the strengths and weaknesses of various languages.

The first few problems can be solved in functional languages like F# or Haskell in a single line of code using list comprehensions. The OO solutions tend to be a bit more verbose and iterative.  Last week I took a bit of time to review some of the solutions that I wrote in languages that I never finished learning and I realised that even to me, the author, my solutions were incomprehensible for the more complex problems. Consider the following lines of code that solves the first (admittedly trivial) Project Euler problem using 2 different languages.

Solution using Clojure:

(apply + (filter #(zero? (min (mod % 3) (mod % 5))) (range 1000)))

Solution using Q:

{sum  x where (0 = (x mod 3) ) or (0 = x mod 5) } til 1000

As a developer these lines of code are fairly easy to understand. Create a range of numbers less than a thousand and then filter out the numbers where the minimum of the modulus of 3 or 5 is zero and then apply the + operator over the filtered list. The reason I understand this is because I dabbled a bit in Clojure and Q. I think that those lines of code are really neat and I love solving problems in a single line of code, however I would not expect a client to understand it.

In the real world, clients do need to understand the solutions that IT come up with. I consulted at a company once where nobody understood a large part of their core system and it was a nightmare for new people. Many of the experienced developers felt trapped and were unable to move on to new projects because they could not hand over core parts of their system to support, or even other developers.

Solution using self-documenting code

One of the primary goals of Warewolf ESB is to avoid these problems of difficult handovers and misunderstanding between clients and IT. Consider the solution to the Project Euler problem outlined in the diagram below. It follows the same step as the solutions above, but it’s incredibly easy to understand.

workflow of project Euler in Warewolf ESB showing self-documenting code

If this were a real world solution, I would be comfortable that if I left a company, the Business Analyst or Product Owner would be able to explain the code above to a new developer and that the new developer would be able to modify it easily.  As a developer working on a solution for a client, I want my solution to be as easy to understand as possible. I don’t want to spend the next 5 years supporting a solution that only I understand, I have far more interesting things to learn and do.

Warewolf provides a way of architecting code that is self-documenting and easily understandable. The architectural patterns of a Warewolf solution are immediately obvious to any relevant stakeholder. The next time that you find yourself writing software that you think will be difficult to understand in the future, consider breaking it up into smaller pieces linked by a Warewolf workflow or maybe even port the entire solution.

If you would like some input in building your first workflow, there is a wealth of information in the Knowledge Base, or reach out to us in the Community Forum.





Leave A Comment?