How I build software: Start with a vision

I’m just starting a new project which is a great opportunity for me to reflect on how I go about building software. Blogging about it means I have to be even more analytical, and also means I can get feedback if I’m lucky.



You’ll see how my primary focus is working around the inherent limitations of my cognitive abilities — I take many opportunities to replace emotion with logical reasoning in decisions making. Also, I try to un-burden my (short, working and long-term) memory as much as possible.



This post shows how I start out on a project by being clear about what I want to achieve.





You might enjoy a quick read of this wiki page about emotion and memory first.

What do I hope to achieve?

If you look at the github repository for this project you’ll see that my vision is:



To create a service bus that facilitates the creation of highly-decoupled (temporal, platform & implementation) business services that can scale horizontally and are highly-resilient to faults.



When I’m designing and building the system I can keep these goals in mind. Any time I need to make a decision, I can use this vision (and motivations below) to guide it.



Without a clear vision I will just have a feeling. Subsequently, this means my current emotional state has a chance to influence the vision every time I think about it. This can result in erratic focus, indecision, or lack of coherence over the life of the project.



Visions are allowed to change. Importantly though, having a vision makes sure that I am logically disagreeing with a written-down statement, not changing goals based on my current emotional state (aka being whimsical).

What is the motivation?

My studies of psychology again lead me to question my emotions and favour a clear, written list of motivations for the project… I don’t want to feel like this project is a good idea — I want written down logical reasons so I can see a purpose to the project and can enjoy working on it (good use of emotion).



As with the vision, a written list of motivations helps decisions to be more logical. For example, the question: “Should I continue with the project?”, can be logically answered by: “do I still agree with the motivations I’ve stated?”.



Here’s what I have for this project at the moment:

• Want to learn more about building distributed systems and middleware
• Want to improve my scala and akka skills
• Need a service bus similar to NServiceBus that works on linux and for any language, for my future projects

What traits should the system have?

I benefit from keeping a small list of high-level properties the system should have which support the vision. Again, these are all about keeping the project focused on solving a certain set of goals. I’m taking work away from my memory and offloading it to a text file.



Importantly I have to think about the traits in more detail too as I write them down. Sometimes they just don’t make sense. Other times they conflict. It’s not until they are written down and logically evaluated that I notice this.



Here’s what I’ve got so far:

• Highly fault-tolerant — as soon as business intent is captured, it should never be lost. e.g. at least once message delivery
• Enables horizontal scalability (as much as it can)
• Easily monitorable (performance of system, errors)
• Primarily to run on linux
• Can be used in any programming language

Todo list and questions list

Any time I realise I need to do something on the project I’ll just put it on the todo list. I avoid holding it in memory or losing focus on what I’m doing at all costs.

Any time I’m unsure about something I just pop it in the questions document. For instance “should network communication be platform agnostic or remote akka?”. I can come back to it later whilst staying focused on the current task.



What’s really important about these simple text files is that they remove the opportunity for my memory to forget the information. Also, just the act of writing down my thoughts forces me to think about them more deeply.



Sometimes, my mind will pick a really stupid answer. But when I write down a problem the obvious solution often stands out. Try it yourself during day-to-day development tasks.

I try to reduce mental workload as much as possible

At this stage of a project I have a good idea of what I want to build and why I want to build it. These reasons are all written down for me to clearly understand over the course of a project — not held in memory as feelings, then re-interpreted through my current state of emotion each time I think about them.



You might think all this sounds like unnecessary work, but for me the pay-off is grand. I work best and feel happiest when my mind is clear to focus on one thing and is not stressed about having to remember important details.



I’m not the smartest developer so I have to get the best out of what I’ve been given. Hopefully you enjoyed seeing how I try to achieve this. In the next post I’ll show I started to design this project and the thought-processes that drive me.