The Accounting Adventure Journal - Episode 01: The Challenge

The following is the report of the first session of the Accounting Adventure.

The time is 31 March 2021 at 9.30. The place is somewhere on the Internet on Zoom. The team is made up of the participants of this workshop: Marco, Nicole, Carlo and I.

In this report, I analysed the things that impressed us most during the session: difficult moments, how we overcame them and, of course, our final feedback.

What is an Adventure? It is a workshop in which I develop real softwre features together with the team participants. We have to solve real software design challenges on a real system. I explain how and why I make certain design decisions or how and why I apply certain practices. Here you can find more about our Software Design Adventures.

Usually, the idea for these adventures comes from software applications that I want to develop and grow: the Tea Assistant or a Video Game. This adventure was born in a totally different way...

The Accounting Adventure

The Accounting Adventure is based on the same requests presented in the SDP Anti-IF The Composite Pattern Workshop: a series of requests from our friend Marc (a fictional customer).

• Marc wants to keep track of his finances and asks us to produce a series of reports generated from the csv file with the collection and payment transactions he exports from his bank.
• Marc tells us a set of rules in order to assign the various transactions to the different categories of costs and revenues. He also tells us the rules for aggregating some of those categories into other higher level categories. An asymmetrical hierarchy of categories, where the hierarchy of cost categories is deeper than one of the revenue categories.
• The first report Marc asks for is to show the total debit, credit and balance for his costs and incomes. Not all of them though. Only for the top level categories (only the first, second and third hierarchical levels - if they exist). At the end of the report, he wants us to show the total profit or loss (the difference between total income and total expenses).

In the SDP Anti-IF The Composite Pattern Workshop, this report was the first request of four that were ready to be developed by participants. Yet most struggled to effectively implement this very first request. The Composite Pattern was clear to each of them. What happened? I asked this question at the end of our session and this was the feedback I collected:

• The first reason is definitely emotional: the inability to handle complexity under time pressure.
• The second reason is the lack of analysis: "jumping" to writing the code without making any effort to verify the consistency of what was requested, to understand the business domain (=the structure of the value to be delivered) and to identify the behavioural scenarios to be implemented.
• The third reason concerns "imposing of a pattern" instead of "letting design emerge". From where? From our communication diagrams, or directly from the code for the more experienced students in our training. All participants had applied the canonical Composite Pattern in a situation where a variation of that pattern or, perhaps, a combination of several patterns was probably required.

Isn't this exactly the same context we find ourselves daily when we develop software? We know design principles and patterns and yet when it comes to apply them something doesn't work. We apply design principles and patterns as we have studied them from really good books and, in the result, software becomes more complicated, it starts to hinder rather than help the development of the next features.

Well, the SDP Anti-IF Workshops are a training aimed to prepare us for those situations. But something had gone wrong... Therefore, we decided to organize an ad-hoc Adventure.

The Process

In the Adventures I develop in first person and the participants work with me... One board, one team... one IDE, one team. For the Accounting Adventure we took the same requests that Marc prepared for the Anti-IF Workshop.

Step 01 Requirements, analysis, use case diagram

We need to understand What to do before we develop it, don't we?

The first thing we did was not to settle for what was written in Marc's request.

• Is everything coherent? The rules, for example? Is there anything missing? Are they coherent with each other? Why are these rules asymmetrical?
• Is the value to be delivered clear?
• Is it clear how to structure that value incrementally?

We spent one Pomodoro identifying the functional and non-functional requirements implicit in the first story so we could highlight possible inconsistencies and ask questions!

Then, we drew a use case diagram on Zoom, identifying "valuable extensions."
If we can identify a set of incremental deliverables, we can work stress-free. And keep our client happy as well!

Step 02 Looking for relevant behavioural scenarios

Time to look for relevant scenarios. Have you ever started to develop a story and put some “ifs” to handle two possible cases (=behavioural scenarios)... and then continue writing code while having to keep in mind what happens in the first and second cases (or in the third and fourth if necessary? :) Well, I do not want this to happen. That's why I only develop one scenario at a time. This increases my motivation and reduces stress.

To do this, I need to identify a list of incremental behavioral scenarios… I pick one… and then come up with a solution (on paper or in code) and then I pick the next one and I come up with a solution... I develop one scenario at a time....

"Real" scenarios

Why did the participants struggle in the SDP Anti-IF Workshop? Because the "real" scenarios were not clear, they were implied but not clearly expressed by Marc.

And when the participants tried to impose the canonical Composite Design pattern... well, they also imposed the scenarios implicit in that pattern... Thus, the design they achieved hindered the achievement of the "real" scenarios... and at that point the "frittata" was done. The software system becomes more structured and complex. Design structures hamper the actual scenarios we have to implement. Anxiety is free to grow without limit.

How to find "real" scenarios when it's not easy?
We can play with objects. And so we did.

We created a digital board... wrote the first use case: "Generate Accounting Report" Then wrote the simplest "OK Scenario" we all identified: "One Salary: 1200 Eur" and started to put some objects on the board. Exactly the same objects that during the workshop didn't really want to cooperate.

We tried to make them communicate with low-level messages at first... then we started looking for higher-level messages and after a few attempts we learned a number of things:

• Transaction does not seem to be the leaf of the Category Composite pattern! Despite the fact that a category (e.g. the "Fun Costs" category) " is an aggregation of different types of transactions (transactions with descriptions related to "romantic dinner", "books" etc.).
• Although Transactions and Categories have behaviors that seem similar, Transactions and Categories seem to belong to two distinct behavioral hierarchies of Composite.
• Transactions could be organized in a second Composite pattern!

Scenarios and complexity

At this moment, a number of new relevant behavioral scenarios emerged... Scenarios related to how to sort the categories out following a certain order defined by Marc (=first all costs, then all revenues and only at the end profit or loss)... Scenarios related to how to aggregate categories... Scenarios related to different ways to assign transactions to categories...

"Maybe we can use Accounts?"
"Is an Account a Category? Or is it a Transaction Container?"

Playing with objects and scenarios lets us answer these questions, following a process, though it might be not easy.

Being able to identify scenarios is important because we develop really complex features keeping the complexity to a minimum. We develop one scenario, complete it and then move on to the next. The increase in complexity we have to manage is always minimal and therefore our anxiety is also minimal. This is important whether you are working in a "traditional" (iterative or not, incremental or not) or in an emergent design mode.

Of course, identifying scenarios is also important to identify tests. Test writing can be driven by incremental behavioral scenarios: we teach our system to behave in a certain way, one scenario at a time. The behaviour of our software system grows test after test (=scenario after scenario), and at the same time, thanks to our objects, its internal structure becomes easier to manage.

Feedback

After four Pomodoros we have not written a single line of code!!! And yet the feeling is very positive. Among the different feedbacks, these are the most relevant ones:

1. We feel in full control. No anxiety. Just the pleasure of understanding the business domain and then being able to come up with a design solution incrementally.

Awareness increases motivation!

2. We like to have a concrete big picture. We worked with communication diagrams to play with objects. This allowed us to look at them "from above" to talk about the ways of letting them "talk" to each other... and it's hard to do the same when you're in the trenches... Deep working in your own lDE, blinking cursor in your method... pondering whether an IF can solve the problem to be solved.

Once you’ve learnt how to play with objects and how to identify relevant behavioural scenarios and develop them one at a time thanks to your useful object, then you can do the same directly from your IDE. But it needs training and that code based emergent design process must not be forced.

Next Step

We told ourselves we wanted to get to the last line of code to deliver Marc his reports .
Let's see where we get to in the next session.