Category: Agile Team

What is good code?
– Defining a common language for discussing code quality

I recently started a new task as Tech Lead for a company that wanted to improve the quality of the code produced by their inhouse team. That immediately posed the question: What is good quality? The question is hard to answer without having a common language for discussing good and bad code. All developers are good at writing if statements, compiling their code and generally transforming the business requirements into software. But taking the helicopter view is definitely not a common task for developers.

So how do I approach such a task? The first thing I did was to spend a few days looking at the code. Even though the codebase is several thousand lines of code, I can get an overview within a fairly short time period. I looked for common anti patterns, e.g. having database specific items spread around the code, having no obvious component responsibility etc. These things point to architectural problems and they are usually the result of having a product with many technical drivers over time. Each time responsibility change, a new direction is decided, but we rarely have the time to clean up the existing code base.

With the overview of the code in mind, the next task is to create a common understanding of the anti-patterns and how to avoid creating new anti-patterns while cleaning the existing anti-patterns. One way of approaching this is to shout out loud that the code is crap. But that will rarely do much on team spirit and it will probably not make the developers take ownership of fixing the problems.

I placed a copy of clean code on the desk of each developer.

I choose a different approach: First of all, we need to define a common language for what good code is. To do that, I arranged a reading group. I placed a copy of Robert C. Martins fantastic book “Clean Code” on the table of each developer and assigned homework. 3 chapters each week and then a meeting where we go through the major points in the chapters. The responsibility for leading the walkthrough is shifting between developers each week.

The book starts out on a quite basic level. How to name things, how to structure code etc. As mentioned before, everybody knows how to write an if statement, but it is surprising how few developers consider naming things. To give an example:
```
If (numberOfItems > 10 && customerLevel == “Silver” || customerLevel == “Gold”) 
{...}
```
Is very different than
```
If (CanCustomerGetDiscount()) 
{...}
```
It is basic, yes, but changing the naming and extracting the if clause is immediately making the code easier to read and code that is easy to read is easy to maintain (or at least a bit more easy).

The book graduately get more and more advanced and touches areas as class design and unit testing.

The idea is that we can create a common language and that the team itself is capable of defining what good code is. Even more important, spot bad code. They need to drive the improvement of quality by themselves, making me obsolete. I will assist them in the journey, advice on implementation strategies, feature design etc., but I cannot improve a huge code base alone.
January 18, 2019
The layered architecture of architects vs. the onion

I have previously blogged about Onion Architecture, in relation to mobile application development, but is it also applicable to the architecture stack of your organisation? I guess it is!

Beware! I will be boxing architects, knowing that in the real world, they might a little more flexible than I try to make them. But very often, they are quite square! So if you want to start the S***storm, please do. I’m wearing my raincoat so it washes right off.

Larger enterprises often have a number of different architect-roles organised in a layered structure. On top is the enterprise architects that have an overall and very strategic look at the different systems and the domains of the organisation. They have absolutely no idea of the actual code being implemented by the delivery teams.

Below the enterprise architects, typically a solution architect is placed. These have the overall architectural responsibility for several applications that together provide a business solution. The solution architects look at the responsibility for each of the applications in the solution and how they interact. They have a little more knowledge about the code being implemented, especially the parts that communicate between the individual applications.

Even lower is the application architect. He/She is looking at the individual layers of the application, how they are secured, how they communicate, how they log etc. This is very application specific, as one application might have a requirement for high performance and as such needs to be architected in a way to support this, while another application need a high level of security (Read more in my post on Non functional requirements as the basis of the application architecture)

Parallel with the enterprise, solution and application architects, typically you’ll see an infrastructure architect and maybe even a security architect. They look at the systems and domains from yet another perspective and provide knowledge and guidelines on how applications should be implemented.

At the lowest level, we find the delivery team. These are the people who have to translate all the ideas that have been grown in the architectural “ivory towers”. They have to translate the architecture into software design and code. This is the place in the value-chain where value as actually added!

The big issue, as I see it, is that the communication rarely jump more than one layer. The enterprise architects communicate to the solution architects, the solution architects communicate with the application architects and the application architects communicate with the delivery teams. In this process, a lot of information is lost and the reason why decisions are made, will disappear. The delivery team will be forced to do certain things without knowing why and that is extremely de-motivating. If you don’t understand why you should do things in a certain way, there is a huge chance that you will actually not do it in that way. I have seen real life situations where the developers – and even some of the application architects did not know the names of the enterprise architects – even in relatively small organisations (<1000)

But how is an onion solving this issue? In the agile world, the concept of cross functional teams are central. In order for a team to be able to deliver, the team must have all the resources needed available in the team. Usually, the team does’nt really need the enterprise architects in the delivery phase, but in the architectural runway before the delivery is starting, it can be very beneficial to organize the architects in a cross functional team. The central part of the team must always be the delivery team. Because if they don’t understand the thoughts and ideas coming from the architects, they simply won’t be able to implement them. The strategic architecture decisions must be made operational, otherwise they are worthless.

The “architectural runway” concept, where a cross functional group define the initial architecture before the development sprints start up, is a brilliant place to gather all the people and make sure the knowledge is passed on to the delivery team. This is the time and place to explain why the responsibilities of one application is defined as they are, why they must communicate the way they do and why they must work the way they do. These are all parts of non-functional requirements. While the functional requirements are elaborated by a product owner next to the team, the non-functional requirements will not be as easily elaborated during the development sprints as the higher level architects typically is harder to access. But the non-functional requirements are also a lot less dynamic and as such, the architectural runway is a great place to elaborate and implement them.

One could argue, that the “higher level” architects just should be available during the delivery phase. This is also correct, but availability also requires that the delivery team actually knows the architects. And having worked together during the architectural runway will increase the social binding and make it a lot easier for the development team to approach the architects.

And who knows.. Sitting in the same room as the delivery team, might give the architects some feedback that they can actually use to improve their ideas.

January 28, 2016
Non-Functional Requirements – The basis of your software architecture
We constantly hear that new applications should use the latest and greatest application architecture… A few years ago everybody was implementing SOA and Onion Architecture, now its CQRS, Micro Services etc. But how do we make a conscious decision on which architecture to choose? The answer is Non-Functional requirements?

What is Non-Functional requirements?

The Non-Functional Requirements (NFR’s) is all the requirements that are not directly involved with the functionality of the application or service being implemented. The NFR’s are typically related to:
- Performance. The expected number of requests that the need to handle. An example on a Performance NFR
  could be:
  Handle 200 requests / pr second on average. Handle 1000 requests / pr second on peak.
- Security. Any requirements regarding security. This can be regulatory requirements etc. An example could be: All sensitive user data must be encrypted. But security can be graduated. There is a hugh difference between creating a system that registers the trucks of a truck company and a system that registers the passport and driver license at a border crossing. Even though both systems might want to secure the data, the consequences of not doing a proper job, is probably a lot worse in the case of passport registration.
- Maintainability. (The cost of fixing bugs)
- Extensibility (The cost of adding new functionality)
- Testability (How easy it is to test the application)
- Scalability (How easy we can scale the number of requests, performance etc)
- Usability (How easy it is to use the application)
Lawrence Chung has a presentation describing the different types of non functional requirements and ways to classify them.

When do we identify the NFR’s

The NFR’s are typically not defined formally and often they are hard to enforce during development and evaluate before deployment. And if the NFR’s are defined, the business owner typically want everything.

“I want a secure, fast, maintainable system that can be extended and scale.”,

quote, The Typical Ignorant Business Person

This is alright. But it is our job as tech-people to explain the price of the NFR’s and the consequences of ignoring them.

Following a strict old-school agile methodology, the NFR’s should evolve along with the business requirements. But this have proven to be difficult as the NFR’s have a huge impact on how the system is build. Performance is hard to add as a feature if the system has been build using a slow technology. Security is often very hard to add as a feature later – if not thought in from the start of the project, there is a huge chance of lots of open attack vector that can be utilized by evil people.

A more “modern” Agile approach, especially for larger enterprise systems, is the thought of having an architectural runway before the actual implementation of the business value. The runway is a shorter or longer period of time where the general NFR’s can be identified, the interaction with other systems in the enterprise can be identified etc and a prototype of the application architecture (A walking skeleton) can be implemented to verify the ideas.

How do we determine the architecture?

The architecture will, unfortunately, not jump into your arms just because you have defined a se

Hammer, Wrench and screw. Its all a matter of the right tool for the right problem.

t of NFR’s. But the NFR’s can be used to determine the application architecture and the design of the application. If performance is of high performance, and architecture where every call to a service have to go through a service broker, e,g, Biztalk, probably isn’t such a great idea. If the business area is changing a lot, extensibility is of high importance, and a very modular architecture is necessary.

No matter what, having a broad knowledge of different types of architecture and their strengths and weaknesses is important.

It is also important to acknowledge that some parts of the business domain might require special treatment, and that could mean that the domain must be implemented in a different way that the rest of the system. If for instance part of the application contains very sensitive data but performance is less important, it might be a good idea to implement this separate from the rest using the proper techniques for that.

It’s all a matter of using the right hammer for the right type of nail. But if you don’t know what type of nail you’re going to use, you might end up with a screwdriver.

Note

NFR’s are not just attached to the general functionality of an application, but also to the individual business requirements which will be handled during a spring. E.g. “The search result must appear within 2 seks.” or “We must be able to process 3000 customers pr. hour between 2am and 5am” are both requirements that are set for a specific user story or feature. And they can be hard to comply with, even though the architecture is well defined up front.
January 14, 2016
It’s not in our scope…. It’s the other team!

I recently participated in a meeting with a development team responsible for a certain part of a solution. The team was responsible for implementing an integration solution between two systems – one system responsible for our business logic and another system responsible for creating customer print.

As the application architect, I have the responsibility for ensuring the technical quality in the solution, but I also have an unstated responsibility to look for the correctness of the solution. It’s not just how it does it, but also that it does the right thing. I had noticed that the solution the team proposed was able to take data from our core system and transform it to the format consumable by the print system. That was the basic requirement. They fulfilled it! But there was a bunch of issues with the solution. If a print didn’t succeed, there was absolutely no way to communicate the status back to the core system.

We called for the meeting to ask for their perspective on this. The answer was CRAZY!

“If anything goes wrong, we will put the failing print job on a fail queue and then we expect the maintenance team to take care of it”

SAY WHAT?

So not only will you not tell the user that it has been failing, but you actually expect a manual process to be set up to handle fails? And extra work on a maintenance team that is already busy handling weird stuff?

This was clearly not acceptable, so we pushed the team a bit. They ended up saying that it wasn’t part of scope for the team and that if it should be in scope, it should be the scope of the core solution team.

What is wrong here?

First of all, the team was clearly aware that things could go wrong, but the team didn’t go to their product owner to mention that something could be wrong with the way the solution was scoped. It is always the responsibility of a professional team to pose questions before implementing things. There is no value in creating a fantastic solution if it doesn’t solve the business problem or actually make the business worse.

Secondly, the team was blaming the other team. THIS is not a constructive way of dealing with problems. In this case, the team couldn’t solve the problem themselves. They needed an endpoint from the other team to communicate status back. This was clearly a joint venture between the two teams.

Third, this wasn’t a question of blaming. This was basically just a question to the overall functionality of the system. In stead of going into defence mode, the team could quickly say that they were aware of the problem and they were in a dialogue with the product owner to solve it in an upcoming sprint.

How to fix this?

One of the problems here is that the teams are divided into technology specific teams – not functional teams. If a cross functional team had the responsibility for the end-to-end solution, there would have been a much higher chance that the team would have found the problem a lot earlier.

Also having a product owner close by would have helped things a lot. Nobody stated the requirement that status should be communicated back to the core system. But if a P.O. is close by, this kind of requirements can be handled and prioritized fairly quickly.

What could I have done to mitigate this?

The problems described above are real. The teams should be cross functional. The teams should take more responsibility etc… But could I, as an architect, have done anything to make things better?

My role in this project is being a cop! I know, it is not constructive at all (I’ll post about this later) but that is just the way it is. As the role of the cop, I called for the meeting. This means that the team is basically in defence mode before the meeting is starting – because they know that I want to questioning their work which makes them less constructive.

What I probably should have done was to ask both the core and integration team to a meeting along with the product owner – with a much more clear agenda that stated that the purpose of the meeting was to find solutions – not blaming teams. Because I just called for a meeting with the headline “Printing solution challenges” I didn’t help out here!

November 4, 2015