Vorgehensmuster für Softwarearchitektur – a Review

A couple of months ago someone (might have been Stefan Zörner) tweeted about an opportunity to get a book for free. Only condition: One has to write a review. This is the kind of deal I just can’t resist. A few weeks later I had the following book on my desk:

“Vorgehensmuster für Softwarearchitektur – kombinierbare Praktiken in Zeiten von Agile and Lean”, which roughly translates to
“Patterns in Approaching Softwarearchitectur – combinable practices in the age of agile and lean” by Stefan Toth

When I first glossed over the title, I thought it is just another book about software architectur. One that tries to teach you how to design your systems in order to achieve a particular goal. That is not the case.

It is about a topic which I haven’t seen covered in any other book so far: How to solve the none technical challenges when working on the architecture of a system.
Things like: How do you get important architectural decissions communicated. How do you organize time for architectural work in an agile project? How do you get from arbitrary statements like “The system needs to be secure” to something you can actually base decissions on.

I think the topic is great. It is important, it hasn’t been covered in other books I know of and the advice in the book is reasonable, plausible and in the case where I already tried the described aproach, basically works as described. This alone is enough for me to recommend this book: If you are responsible for architectural work in a software project, get this book and read it. This of course asumes you can read German. If not, well I hope the book get translated to English, it’s worth it.

Sounds like 5 star review? Well, no. While the pure information contained is great value, there are other things to consider: Appearance and Style. The book comes in the standard binding of the German publisher Hanser. It has a thicker cover than a nromal paperback but still some flexibility. The combination makes a easy to handle and durable book. Full points on this category.

The thing I don’t like to much about the book is part of the writing style. It is structured in patterns and each pattern is introduced by a dialog between 2 or more developers. I found these dialogs just boring and repetitive because after the dialog the topic gets introduced again in a more formal way. So I think the dialogs are superfluous.

After the problem statement and the description of the proposed solution there comes another section where the pattern is turned around. The section advices you how you can use the pattern to actual make your project fail or at least suffer. When Stefan introduced this in the beginning of the book I though “Cool, fun idea!” But when reading them I actually didn’t liked those sections at all for two reasons:

  1. The proposed aproaches to make a project fail where pretty uninspired in most cases.
  2. I still found my self reading these sections and completely forgetting what I was reading. So I thought “Holy s**t, what kind of nonsense is this!”, just to realize what part I was reading half a second later.

So to sum it up: Do get the book and read it. Just don’t expect a world changing piece of literature.

Your Code ain’t your To-Do List

What do you do if you find a problem in your code base but can’t fix it right now? If you are like many developers you probably put something like a todo comment next to it, so you don’t forget it. Something like:

// TODO: We really need to move all this stuff into a seperate class it really has no bussiness here.

The great thing about this kind of comments is: The IDE can pick them up and display them in some kind of list.

But the problem is (at least in my experience): It doesn’t work. Lots of those comments hang around for months and even years, often until the code around the comments changed so much nobody knows what the comment is supposed to mean. I have even seen TODO comments copied around with the code they are embedded in (which of course is a symptom of another problem).

You might know the book “Getting Things Done” (GTD). If not, read it. It’s good stuff. One of the key points of the book is: Your inbox isn’t your to-do list. Meaning you don’t use your inbox (where stuff you have to do arives) as the list of things you actually have to do.

In your inbox you have no way to properly control, what is important and what is urgent. Nor do you know if the task is something that takes two minutes or two weeks, or if it has a specific due date on which it has to be finished. Therefor the recommendation of GTD is: Get you inbox to zero by reviewing everything in it and either doing it right now if it is quick or transforming it in a proper task and filing it to one of various lists where you can pull it from when you have time to do stuff that takes longer than two minutes. Those lists cary with them all the information to decide quickly what task you should tackle next.

The same thing applies to TODO comments in your code. Code is great for many things. Managing tasks isn’t one of it. But you probably already have some kind of issue tracker in your project. If you find something that needs fixing in your code: put it there. There you can discuss it, compare it to alle the other tasks at hand in order to decide what is most important.

As every rule it comes with some exceptions: Short lived TODOs are fine in your code. Like when you implement a new feature and suddenly realize two more tests that you need to implement. Go ahead put a TODO in your code. Just make sure you’ll remove it and replace it with actual code before your next push to the central branch.

For everything else: don’t misuse your code as a to do list.

Tons of Small Classes

When I do Clean Code Training or if I discuss the topic with coworkers one argument comes up over and over again:

“But if I have split all my code in those tiny methods and classes, how will I find anything? I’ll have to navigate through dozens of files!”

The problem with this argument is: It is not that wrong. And I have certainly seen code where I had to navigate a dozen classes very carefully in order to understand what is going on.

If you look at it from an abstract point of view it looks like it even has to be this way. If you want to completely understand a piece of code it’s certainly best, to have it all in one piece on the monitor. You can go from top to bottom, line by line. If you have lots of little methods and classes, you in addition to that have to navigate through all that classes and methods, keeping track on from where you called this piece of code. Obviously these are additional tasks that just make your work harder!?

I still insist this argument is wrong. The mistake is the premise that the task at hand is to understand all the code.

It is very limited what you can keep in your brains working memory at any given time. So for any non trivial program the task to completely understand it is not feasible.

The real task at hand is to

  1. limit the amount of code you have to understand
  2. make it as easy to understand as possible

The key to that is abstraction!

Let me ask you a question: How often do you use a HashMap or what ever the equivalent in your preferred programming language is used? Probably many times a week, right? But how often do you actually look into the source code of a HashMap? Probably next to never! We just know what a Map does and that a HashMap is one very good general purpose implementation of it. That’s all we need to know about it. We just use it. We just know how it behaves. We just understand what is going on when it get’s called.

If your abstractions, i.e. your methods and classes are just like that, you don’t need to look at their source code most of the time. You just read the name and you know what it does. You probably don’t know how it does it. At least not in detail. But you don’t need to. If you know what it does, you know enough to decide, if you need to step into that class or not, for what ever you try to achieve right now.

Of course if what your classes and methods do isn’t as obvious as a get on a HashMap you still have room for improvement.

Softwaredevelopment, Projectmanagement, Qualitymanagement and all things "schauderhaft"