Blog

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
Download Free Pester Cheat Sheet

I recently started testing my PowerShell scripts using the Pester framework. The documentation on GitHub is excellent but I was missing a cheat sheet that can be printed and used as a reference while learning.

So I created it.

Download Pester-cheat-sheet 1.0.1 here and share it in your office. If you like it, please give a heads up on twitter.

May 18, 2016
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
Tabbed Page icons are case sensitive

I have just spend most of an hour to make the app I’m currently doing work on my devices. I have been working in the simulator during development, and everything has been great, but when i deployed to my iPhone, the app just stopped working. I didn’t close down, but it didn’t load completely either.

I basically started to comment out code, and finally, I got around to a tab page, that i create at startup:

public classFrontPage : TabbedPage
{
public FrontPage()
{
this.Title = “Lean Priority”;
Children.Add(new ProjectOverviewPage());
Children.Add(new ContentPage() { Title = “Help”, Icon = “help.png”, Content = new Label() { Text = “Foo” } });
Children.Add(new AboutPage());
}
}

The problem turned out to be the icons. I entered Icon=”help.png”, but the icon in the resource folder was named “Help.png” – with a capital “H”. Apparently the simulator doesn’t care about casing, where the real devices do. The problem is, that you don’t get any errors when the icons can’t be loaded. The app just stops loading.

July 17, 2014
Passed the certification exam

I just passed the Mobile Developer Certification Exam – but just barely with 80% correct answers. The exam contained a lot of questions about compilation, garbage collection etc. as well as some more general questions regarding software development.

Xamarin has chosen ExamBuilder as the software provider for the exams. I had a lot of problems with this. During the first half hour of the 3 hr. examination, I lost connection with exambuilder at least 10 times – where I had to log out and log in again. This was quite annoying even though it got better as the exam progressed. I hope I was just unlucky.

June 15, 2014
Onion architecture with Xamarin and PCL
Over the short history of Xamarin, there has been a bunch of different ways to share code between platforms, when using Xamarin to create IOS, Android and Windows Phone applications. At first, there were only simple ways to share code, like file linking where the developer had to drag and drop files from one code project to another. If the shared code needed to do anything platform specific, the code would need to be filled with #IFDEF statements to target each platform.

This approach is problematic: If the code that needs sharing is spread over multiple files, all the files has to be linked – and most projects would have a high number of files all needed to be linked. Another problem is the IFDEF statements. It is basically a violation of Separation Of Concerns, when a class can handle multiple platforms. In stead the code should be separated in different classes and the dependency framework should inject the proper code for each specific platform

Portable Class Libraries

Near the end of 2013, Xamarin announced support for Portable class libraries in cooperation with Microsoft (http://blog.xamarin.com/pcl-projects-and-vs2013/). The Portable Class library (PCL) makes it possible to share an entire assembly using the same project referencing techniques known from other platforms like web and windows projects. Just create a PCL assembly, add your shared code, add unit tests etc, and then reference the project from your main application or another PCL library.

When creating a PCL project, you have to choose a profile for the PCL. The profile basically describes which platforms the PCL should target. The more platforms you choose, the more restrictions you will have on the .net framework features available. If you for instance choose to target Windows Phone, the PCL will not be able to use HttpClient directly.

Onion Architecture

Onion Architecture was originally described by Jeffrey Palermo back in 2008 (http://jeffreypalermo.com/blog/the-onion-architecture-part-1/) and it has a history going even further back. Its a widely recognized architecture when using domain driven development and IOC.

The architecture describes a core which only contains a domain model. Around the domain model, there is a bunch of domain services, who knows the core. But the core has no knowledge about the domain services. So all references goes from the outside to the inside. The next layer is application services and UI / infrastructure. The UI is kind of self explaining, but the infrastructure needs a few words.

Lets say the application needs to read information from a file. In stead of placing this functionality directly in the domain services, the service will provide an interface and code against this interface. The actual implementation of the file writing functionality is placed in the infrastructure layer and injected into the domain service layer through the use of IOC.

Given we want to retire early, I want to create a competitor to Instagram and sell it to Twitter for an insanely large figure. But I will start simple though. My app will only be able to capture an image and save it to disk.

My domain model (core) would look similar to this.
```
namespace MyApp.Core.DomainModel
{
  public class Image
  {
    public Image (byte[] imageData)
    {
      ImageData = imageData;
    }
 
    public byte[] ImageData 
    {
      get;
      private set;
    }
  }
}
```
The domain model is simple and reflects my only domain which is the image.

I need a domain service to actually capture images and store them somewhere. But as this is platformspecific and uses infrastructure that is different on each platform, I choose to implement my domain service as an interface.
```
namespace MyApp.Core.DomainServices
{
public interface ICameraService
  {
    MyApp.Core.DomainModel.Image CaptureImage();
    void SaveImage(MyApp.Core.DomainModel.Image  image);
  }
}
```
Another important benefit is, that my app, so far hasn’t decided weather the image should be saved as a file or posted to an online account. All this depends on the implementation of the interface.

On top of this simple domain model and service, I will provide my most outer ring of the onion. Off course I provide a UI for IOS and another for Androind. But I will also provide an implementation of the ICameraService, that will actually capture images on each platform.

The result is that all code that can be shared, is shared and platform specific code i separated between the platforms.

I will end up with a solution looking like this (ooops… forgot my unit-test projects)

Why is Onion Architecure such a great fit with Xamarin?

Xamarin gives the advantage, compared with other x-platform tools, that you can share native code between platforms and only provide platform specific code for the parts of the code that differ for each platform. This model fits perfectly with the onion architecture, where all code in the inner circles of the onion is general and can be shared between platforms. The code in this part of the onion should never contain platform specific code and even the most restrictive PCL profile should be useful for this.

There is a bunch of solution templates available for making Xamarin based apps using the onion architecture. Take a look at these links and try it out.

https://github.com/Kizmar/xDriven

https://github.com/OSTUSA/xdriven

_
May 25, 2014
Studyguide for Xamarin Mobile Developer exam

I have collected the links to additional information provided in each of the session videos. If any links are missing, please add them in the comments. The link collection can be used as a studyguide for Xamarin Mobile Developer Exam.

XAM101 Intro to Mobile / Kickstart
http://docs.xamarin.com/guides/cross-platform/application_fundamentals/building_cross_platform_applications/

AND101 Intro to Android with Xamarin Studio
http://docs.xamarin.com/guides/android/getting_started/

AND102 Intro to Android with Visual Studio
http://docs.xamarin.com/guides/android/getting_started/

IOS101 Intro to IOS with Xamarin Studio
http://docs.xamarin.com/guides/ios/getting_started/

IOS102 Intro to IOS with Visual Studio
http://docs.xamarin.com/guides/ios/getting_started/

AND101 List Views and Adapters in Android
http://docs.xamarin.com/guides/android/user_interface/working_with_listviews_and_adapters/

IOS110 Tables and Collection Views in iOS
http://docs.xamarin.com/guides/ios/user_interface/introduction_to_storyboards/
http://docs.xamarin.com/guides/ios/user_interface/tables/
http://docs.xamarin.com/guides/ios/user_interface/introduction_to_collection_views/

XAM140 Introduction to Cross-Platform Mobile Development
http://docs.xamarin.com/guides/cross-platform/getting_started/introduction_to_mobile_development/
http://docs.xamarin.com/guides/cross-platform/application_fundamentals/pcl/introduction_to_portable_class_libraries/

XAM150 Introduction to Cross-Platform Web services
http://docs.xamarin.com/guides/cross-platform/application_fundamentals/web_services/

XAM160 Data in mobile
http://docs.xamarin.com/guides/ios/application_fundamentals/working_with_the_file_system/
http://docs.xamarin.com/guides/cross-platform/application_fundamentals/data/

XAM205 Mobile Navigation Patterns
http://docs.xamarin.com/guides/android/platform_features/fragments/
http://developer.android.com/guide/practices/screens_support.htmlhttp://docs.xamarin.com/guides/ios/user_interface/creating_tabbed_applications/

XAM210 Backgrounding
http://docs.xamarin.com/guides/cross-platform/application_fundamentals/backgrounding/

XAM220 Publishing an App
http://docs.xamarin.com/guides/android/deployment,_testing,_and_metrics/publishing_an_application/
http://docs.xamarin.com/guides/ios/deployment,_testing,_and_metrics/app_distribution_overview/

AND230 Maps and location in Android
http://docs.xamarin.com/guides/android/platform_features/maps_and_location/

IOS230 Maps and location in IOS
http://docs.xamarin.com/guides/ios/platform_features/ios_maps/

May 20, 2014
Review of Xamarin 140: Intro to Cross-Platform Mobile Development

Im just about to join a session on Xamarin University, XAM 140: Intro to Cross-Platform Mobile Development. I spend last night reading through the course material made available by Xamarin University. And basically this course is about two things:

1) Learning how to reference a shared assembly

2) Learning how to link to a shared file

My impression is that attendees at Xamarin University already know how to do regular .net development.

Hence is referencing a shared assembly very very basic. And sharing functionality by linking files is probably possible (I guess its also possible using Visual Studio) but it is definitely not a good way to share common code between projects.

I really hope that the course will bring me more than mentioned above. Otherwise it will be a waste of time.

Most amazing is, that this course is mandatory (1 of 3 courses) to take the Xamarin Certified Mobile Developer exam.

—

Follow up: Im disappointed. The class did not go through anything but referencing assemblies and using a “worst” practice of sharing files. At least the tutor told that this isn’t an optimal way of sharing stuff.

I hope to see a class of real cross platform mobile architecture. I have a clue that the use of Onion Architecture will be optimal for Cross Platform Mobile Dev.

March 19, 2014