Tag Archives: architecture

Is your software architecture explicit?

Posted on by

You know, every system has a software architecture and a software design. Whether you think about your system’s architecture or not, it will have one.

Here is an example of two methods in a class I recently saw. It is not architecture, it is good old OOD, but it exemplifies what can happen if you do not think before you code.

protected String getSystemArg(final String key) {
  return parameters.get(ARG_PREFIX + key);

public Map<String, String> getSystemArgs() {
  final Map<String, String> map = new HashMap<String, String>();
  for (final Map.Entry<String, String> e : getParameterMap().entrySet()) {
    if (e.getKey().startsWith(ARG_PREFIX)) {
      final String newKey = e.getKey().substring(ARG_PREFIX.length());
      map.put(newKey, e.getValue());
  return map;

Both methods in the class handles the same parameter map. The first method returns a “SystemArg” for a specific key from the parameter map. The same parameter map that the second method in some obscure way gives you in total (but with keys without the ARG_PREFIX).
The first method is protected. The second is public. Which one would you have used if you have a key for which you want a “SystemArg”? Which one would you like to use?
This is an example of what you get if you do not think about your design. A public interface of a class that blatantly shows the inner workings, and a protected interface that is what should have been the public one in the first place.

To me, an explicit architecture is visible. All team members knows about it, i.e. it is well communicated. To make such an architecture you need to be aware of the decisions you make and why. This means that the team(s) need to have discussions, perhaps draw some interaction diagrams on a white board, maybe make a domain model and whatnot. Just do something. Anything is better than nothing.

White board area next to Sprint Backlog

White board area next to Sprint Backlog

Example of explicit architecture

Example of explicit architecture.

Agile does not prohibit you from doing design or architecture. It certainly does not prohibit you from using your brain. It only states that you shouldn’t do it all upfront, but rather evolve it over time, just as your requirements evolve. So please, think about your architecture and make it explicit. Because if you get an implicit architecture, you will be knee-deep in technical debt and then you will call me to come and fix it…

Why do we never get the time to work on system architecture?

Posted on by

Have not all of us been in a spot where we feel an urgent need to fix some quality such as performance or availability, which takes a change in the architecture for effect? And yet we are pushed to work on new features instead?

There is a chasm between the tech side and business side that has to be bridged before a sound dialogue about system architecture can take place.

read more »

State of My Agile Mind

Posted on by

It has been 10 years since the Agile Manifesto was written and although I have not been following the agile community for that long, I have been a developer in Scrum teams since 2007. In total, I have done system development for 30+ years so I have lived and breathed both waterfall and RUP before trying Scrum.

So what is on an agile developer’s mind these days? Here are my current reflections on three things today, Agile Development, Architecture and Acceptance Testing.

read more »

Agile and Architecture

Posted on by

Yesterday I held a presentation on the subject “Agile and Architecture” at EDB. They have an internal competence network which meet regularly and discuss agile processes and methods.

My point in this presentation was that every system has an architecture that determines the qualities of it. Given a set of functions, different architectures will give these functions different qualities, such as performance and cost of maintenance.

This is still true, no matter if you do waterfall, RUP or Scrum.

What is different, however, is how we work with architecture. We became agile to cope with a faster changing world. So the architecture must be changed at a much higher pace now than before. Architecture, though, is known for being hard to change. After all, it is the pillars that the system stands on.

I held an exercise, or should I say, tried an exercise. But, gosh, what a cheat these cloud computing services are. 🙂

Ok. Here are the slides.

Design Principles for Error Handling

Posted on by

Besides understanding the most important structures of a system, it is an architect’s responsibility to understand and influence the design principles.

One common and important set of principles are those of error handling. It is good to have the same principles throughout the system as it produces fewer surprises and mistakes.

In this post, I will discuss you some principles that including checked exceptions and Null Object, which you may not fancy. But it is always good to think this subject through, so please come along.

My first principle is: "Deal with the errors directly".

What? Errors happen. Not my fault. Somebody else will have to fix this.

My point is that you should try to design your interfaces so that the implementation has a slighter risk of failing. E.g. a function called "getSingleResult" is asking for trouble. Either you get more than one result  or you get none. In either case, you have to do something.

It is better to return a set of objects and let the client determine if the result was good or bad.

If you are asked to read object x from file y, you could return a Null Object if there is no x object in file y or if file y does not exist. Should the client think it is important whether there is a file y, it could find out by other means. You can not protect the client from the fact that a file is missing. It is annoying if all clients need to catch a FileNotFoundException when most of them would be happy with a Null Object.

The second is: "Tell your supervisor".

When you were a newborn you probably screamed when you were hungry. Later

you got old enough to ask for food.

The same goes for exceptions, you are just screaming that something is wrong and that someone else should fix it.

Instead, you should call your supervisor. There are times when you will be asked to deal with data that is inconsistent or use resources that you can not locate. Go call support. Writing in the log is ok if you have a tight check on your log scanning. Maybe there are such people out there. Otherwise the system should have a mechanism for calling support, so to speak.

Other than calling support, you should be silent. At least try to shut up.

The third is: “Use Null Object Instead of null”.

A bit Java specific, but it applies to other languages as well.

As soon as somebody returns a null, be it an innocent getter function, someone else will either have to check that or get killed by a NullPointerException. I hate those.

You may think that returning null is a perfectly sensible way of telling that nothing is there. Now we have exceptions to tell that us something is not ok, so we do not need return values that indicate errors. The benefit is that we do not have to get our code messy with checks after each function call.

Like this:

int error = dothis(withobj, toobj)
if (error != ERROR_OK) return error
error = dothat(someobj)
if (error != ERROR_OK) return error

Get it? Why would I need to do the same with null when calling your code?

Use a Null Object instead. Let me decide if I need to know that there was nothing there.

If you design with “tell” rather than “ask”, it is easier to avoid both null and Null Object. Imagine having no return values, all methods have the void return type.

The fourth is: “Use Checked Exceptions”. (Java specific)

Now, remember that you should follow the other principles, but if you are going to throw an exception, why not tell your client beforehand? I mean, if you throw an unchecked exception, your client is caught off guard and will go down.

The objection is that the client code gets messy as it is forced to catch exceptions which it has no idea what to do with. Now, if that is the case, there is something wrong. It should be evident to the client what it should do.

Take login as an example. If you have a function “loginUser(user, passwd)”, it could fail for both technical reasons or wrong credentials. Either way, an exception will be thrown.

Now, since it is a login function, it is evident that the client would like to tell the user why it failed by showing an error message and remain on the same page. It is not messy, it is natural and better that returning null or throwing an unchecked exception.

If you design the function as "isCorrectCredentials(user, passwd)" you are asking for trouble as the login may fail for technical reasons as well as incorrect credentials.

As you may have noted, you should know your clients. Try to walk a mile in their shoes,  i.e. try to use your own interfaces with a critical view. Look at actual client code.

Remember, these are only suggested principles. Make sure you have some where you work today!

Stable Interfaces – any good?

Posted on by

I once worked in a rather large project, about 1000 persons. There are many stories about that project but the one that I’m thinking of now is that we loved to say "stable interface, we must have stable interfaces".

Now, stable means not changing which means nothing gets better. So why would anyone want stable interfaces? And what should we say about the opposite, "unstable"?

Stable interfaces is a cornerstone in tactics for modifiability, so how do stability and modifiability go hand in hand?

Do you see my finger?

No, I am not doing a rude gesture, don’t worry. The fingers, part of the hand, are so powerful because, among other things, they bend a specific points, the joints.

So a finger is flexible, to a certain extent, which makes it more powerful than if it could bend any imaginable way.

The joints of a finger are the stable interfaces in your system’s architecture. E.g. we want to modify the system by adding new modules in runtime. So we define plug-in interfaces that the modules adheres to and uses for interacting with the rest of the system.

Those interfaces must be carefully designed as we don’t want to change them. Should we change a plug-in interface, every module would have to be rewritten and retested.

So some interfaces really need to be stable. But other interfaces we change all the time. Every class in your code has an interface so you can’t do much without changing that. It will affect other parts of the code but thanks to type safe languages and automatically running tests, it is not as bad as it used to be.

Bottom line. Some interfaces are part of an architectural strategy and need to be stable therefore. But most of the interfaces really need to be on a roll.

Understanding a System

Posted on by

Understanding a system comes in pieces but each piece can take longer or shorter time depending on the circumstances.

What does it mean, then, to understand a system?

Well, if you don’t understand it and introduce a change, you risk going wrong. The code you wrote may seem to work, but …

 – You put the change in the wrong place so everyone else is confused.
 – Your unit tests ran fine but some other part of the code wasn’t under test and stopped working promptly.
 – Your change introduced a dependency to another component and we now have a circular dependency.
– The system can’t be deployed because there was a distributed interface which you thought were local.
– You didn’t follow the policies of error handling, logging or security. So now there is a security breach which is not caught by error handling and the log is nowhere.

So that’s the "why" of understanding. The "how" has some answers you probably know already.

  1. RTFC: Read The Fine Code. Yeah, that’s what we do. All the time. Don’t tell me to do something I do all the time. Thank You.
  2. Ask a Guru. There are gurus? No, guru means teacher which means the opposite of withholding information. That’s what some do, to be in need. Baaad. But you have to deal with it more often that you wish.
  3. Write unit tests until you get it. No harm in that if you do it as you go.

All these have the drawback of looking at the details without seeing the big picture. It reminds me of when I was 13 and learned the city by areas around the subway stations. After a while the areas got big enough to connect to each other and I could get the overall picture without looking at the map.

What is the big picture then? Well, it is the architecture of the system. There is no mystery about it, no magic patterns put down by a long gone super genius, no outdated ideas, just plain descriptions of how the system is designed.

Like a house is understood from blueprints of the outside, the disposition of rooms, the plumbing, etc, a system is understood from different views. There is a standard that will tell you that there are views but leave it to the author to decide which views.

The one I have seen most of is Kruchten’s 4+1, published in IEEE Software. You should be familiar with it but I guess you are not. I have a course on system architecture and I am still surprised how few of the students that have ever seen a document describing a system’s architecture, despite several years in the business.

The crash course is to study the Wikipedia article linked above. Start with the logical view and the physical (deployment) view, those are easiest to grasp.

But there is more to it. Remember that I said something about going wrong with logging, error handling and security? Those are principles of the design and impacts the system almost everywhere.

So to understand a system, I think you need the details and the views and principles of the big picture.

Oh, was the Wikipedia article too long? Here is a cheat sheet:

  • logical view: how components of the system relates to each other logically.
  • physical view: the servers and firewalls and stuff like that.
  • process view: how processes and threads are related.
  • development view: where the compiled code is package, e.g. a war.
  • scenario view: important functions of the system.

Qualities Attributed to the Architecture

Posted on by

Functional requirements describe how a system delivers value. However, the quality attributes of those functions will make or break it. For example, if your functional requirment is about something that takes you from one city to another, I have a car to sell. Really cheap, for that matter.

Every system has an architecture. It may be elegant or it may be ugly. It may be described or it may be unknown. But it is.

Architecture is what determines the qualities that the system delivers. Is it fast? Is it secure? Can it be extended? Does it scale?

The qualities you strive for should determine the design of the architecture – not the other way around.

What do I mean with quality, then? I’m not in the philosphical mode today so there will be no Zen-talk. I’m simply refering to measurable requirements such as response time and throughput. Quality to an engineer.

Some say non-functional requirements. I’d say, stop saying that!

You can’t have response time without refering to a function or a group of functions. E.g. all interactive functions. Therefore, "response time" is an attribute of those functional requirements.

Since it is an attribute, it does not live on its own. There has to be a functional requirement, at least one. Also, functional requirements always have attributes even if they are not determined or poorly understood. Remember the cheap car? Well, forget it, it disintegrated on the way to that other city.

So, once you have understood what quality attributes are, why should it matter? Well, my point is, it is about the design of your system’s architecture!

It is how you divide your system in components, software-wise and hardware-wise, how these components interact and how new components can be added, that determine qualities of your system.

Say, you like security for your website. Is that a requirement on the website? No, it is the requirment on some of your pages. You probably have at least one public page.

So you decide you need people to login with name and password. That doesn’t make your system deliver any value to anyone, it only lowers usability. But still, you need that security so you put in some components for that. Considering using LDAP? Well, here comes a LDAP-server to your architecture.

Not all quality attributes determine architecture but those that do, are really handy when it is your job to design the architecture. They help you by narrowing your design options. Stay tuned.

You think architecture means Big Design Up Front (anti-pattern from the agile community)? Wrong. Every system has an architecture, regardless of you did it in increments or in one go.