In 2012 I gave my first talk on typography on the web. Titled Web Typography Now it documented the evolution of type on the web and was timely as universal @font-face support had just landed in all the major browsers. At the same time Open Type features were gaining support via the lower level CSS properties. It was an exciting time for type enthusiasts as we saw a brave new browser world not shackled to the six or so web safe fonts.

![Image depicting the title of a typography talk](/uploads/typography_talk_86e72917f2.png)

Of course our new found type abilities came with drawbacks. Older versions of Internet Explorer needed a proprietary format. As did early versions of iOS. Performance was a major issue due to browser handling of font downloads and CSS parsing. More often than not we were faced with the horrors of Flash Of Invisble Text (FOIT), rendering the page unreadable until the font file finished downloading.

Over the years I have updated my typography talk. It has been presented a number of times in various formats. At meetups ([DevUg](https://developerug.org.za/), [IO](https://io.co.za/)), at conferences ([DevConf 2019](https://www.devconf.co.za/), [UX Craft South Africa](https://uxsouthafrica.com/)) and in a series of workshops for CTFEDs.

Recently I presented the latest version at a FEDSA meetup. Titled Dynamic and Performant Web Typography it covers tips for selecting and matching typefaces, the latest techniques for optimising custom font performance, and how to use modern CSS for fluid type that scales seamlessly across devices.

As we now seem to do everything via Zoom (or similar tools), the talk was recorded and you can watch it on the [FEDSA YouTube Channel](https://www.youtube.com/watch?v=9ckzkm3VNFU).

One thing that came up in the discussion was around a list of resources on web type. I am currently putting that together in a GitHub repo and will update this post when it's ready.

In 2012 I gave my first talk on typography on the web. Titled Web Typography Now it documented the evolution of type on the web and was timely…

Dynamic & Performant Web Typography

Layout on the web has always been very difficult because of a lack of real tools to accomplish this task. All manner of techniques from tables to floats, positioning, and display properties have been used in an attempt to emulate designs and create usable interfaces for the browser. While disparate all these techniques have one thing in common: they are by and large hacks.

![Image depicting a potential web layout](/uploads/layout_talk_a5c475ffc5.svg)

With the advent of Flexbox and latterly CSS Grid, as well as a whole host of other layout properties such as object-fit, writing modes, shapes and box alignment (to mention just a few) we are finally getting the tools we need to do layout on the web.

Recently, I gave a talk at a FEDSA meetup tracing the history of web layouts and demonstrated some of the new techniques at our disposal to create modern, designed interfaces with our new layout tools.

The talk was also recorded and you can watch it on the [FEDSA YouTube Channel](https://www.youtube.com/watch?v=UurfdK8Hlnc).

With the advent of Flexbox and CSS Grid, as well as other layout properties such as object-fit, writing modes, shapes and box alignment, we finally have the tools we need to do layout on the web.

Modern Layout On The Web

The only unfortunate thing about [Microsoft Azure DevOps](https://dev.azure.com/) is that they chose to use "DevOps" in the name, the latest and greatest buzzword right now. The rest of the news on Azure DevOps is almost exclusively good.

I decided around March of 2018 to move NML from our existing development cloud solutions to Azure DevOps. It has turned out to be one of the most impactful and positive changes we have made this year, and I hope to shine some light on why in this article.

## The beginnings

NML has always relied heavily on cloud platforms for most of our software needs. It is a cost-effective way to operate a small to medium business, especially in the software industry. At the beginning of 2019, the cloud services we used looked as follows:

- Atlassian Jira
- Atlassian Jira ServiceDesk
- Atlassian Jira Confluence
- Atlassian Bitbucket
- Octopus Deploy
- Microsoft Office 365
- Microsoft Azure

NML is almost exclusively a Microsoft stack service provider, but we embarked on our cloud journey long before Microsoft had an offering like Azure DevOps in place. As such, we developed our business along the Atlassian line of cloud products.

## Why move

The Atlassian suite served us well enough, but it would be a bald-faced lie to say I am a fan of any of the Atlassian cloud platforms. Octopus Deploy was a much later addition as our builds and releases were generally done on Jetbrains TeamCity.

### Administration

My biggest grievance with the Atlassian suite of products is that they are just too complicated to manage. You almost need a doctorate just to open the administration sections. Take note of the plural: "sections"! With enough time and anti-depressants, one could usually eventually navigate your way to what you wanted, but you have to set aside at least 2 days to get anything done. And you have to go through that every time since there is virtually no way you can remember what you did previously over a length of time.

### Cost

Each platform requires you to have different licenses, which can make it quite an expensive proposition. That is to say, you have to pay for Jira and ServiceDesk and Confluence and Bitbucket and TeamCity and Octopus Deploy all separately!

### Complexity

You have wildly different user experiences when working across all these different systems. It is a rather huge barrier to entry for newcomers. You have to have different introduction sessions to cover each and the poor soul that has to keep up with each platform's particular nuances had no chance to get it right.


### Identity

Identity management is a complete nightmare. In an age where there is a potentially fatal security incident around every corner, identity management is critical. Each user on each platform needs a different account. In fairness, Atlassian does have a single identity across its platforms, which helps some. But even there you have different user experiences, between Bitbucket and the Jira suite for instance.

### Effectiveness

Lastly, it is a huge drain on effectiveness to hop between platforms while carrying out one's duties. As a developer, you need to view your story and tasks on Jira. Additional info might be in Confluence. You have to pull your source code and view pull requests on Bitbucket. Builds on TeamCity and deployments on Octopus deploy. Every time you have to switch to a different system, there is a certain level of context switching that goes along with it. I have yet to experience positive context switching in my career.

## The new state

Our current state of affairs looks as follows:

- Microsoft Azure DevOps
- Atlassian ServiceDesk
- Microsoft Office 365
- Microsoft Azure

As you can see, it is a much shorter list and we are without a doubt better off on each of the pain points.

### Administration

DevOps is much, much easier to configure than Atlassian. It is not nearly as configurable, though. That said, I have not missed a single one of those extra configuration options.

Somehow, Azure DevOps has the balance just right, and my experience is that when I am looking for a configuration to achieve something the way Jira does it, it is more as a result of my ignorance on how DevOps approaches the problem.

### Cost

Azure DevOps has a pretty simple licensing model and it will suffice to say here that we are paying tens of thousands of Rands less per month. There is not even a comparison to the cost differential. The simple reason is that we only need to pay one license for all the features we need.

There are additional costs one needs to be aware of, for instance reserving pipeline hosts, but that is more than covered by the savings on TeamCity and VM licensing alone.

### Complexity

Our ecosystem has reduced by 3 platforms. Almost all the work a newcomer will do upon joining will be exclusively limited to Azure DevOps. We have therefore removed a huge hurdle to team integration for new joiners.

Azure DevOps offers a single user experience to

- Manage sprints, stories, and tasks
- Manage repositories and pull requests
- Configure builds and releases
- Manage quality assurance

### Identity

The remaining cloud services, except for Jira ServiceDesk, use Microsoft identities associated with NML. In other words, you only need to log in once. Additionally, we can enforce best security practices like multi-factor authentication, role-based access control (RBAC), etc across the whole business on our most critical platforms. It is incredibly useful to be able to manage all user access to your various platforms from a single place, Azure Active Directory.

### Effectiveness

This is only anecdotal, but I strongly believe our teams' effectiveness has improved. We now have seamless integration and tracking from stories to commits to releases. Also, nobody on the team needs to hop between various platforms or interfaces to perform their work from start to finish.

## More

The above items are just the pain points Azure DevOps helped us with. Here are some more wonderful features that make it worthwhile:

### Incredible build and release system

The builds and release in Azure DevOps it super easy to configure and maintain. They have extensive support for various build types and release platforms. For example, one of our most used builds pipelines relies on Jekyll, a distinctly non-Microsoft solution. We also generate beautiful release notes by leveraging the integrated nature of stories and commits.

### Quality Assurance

Testers and the testing effort is part of the project delivery with Azure DevOps. It has been a complete life-saver for us in establishing a working test regime that can verifiably assure quality delivery.

### Pull Requests

The pull request system is sublime. You can automatically run CI builds and require it passes for new pull requests, require a minimum number of approvers, require a work item to justify the pull request, etc, all as part of a repository branch policy.

## Conclusion

Our experience on Azure DevOps has been overwhelmingly positive. I put this down in large to the fact that we are a Microsoft stack company and are already comfortable with and pretty well embedded in the Microsoft scene. However, I think Azure DevOps has a much broader reach than a Microsoft context, and can very easily work for any technology stack.


The decision to move NML to Azure DevOps in early 2018 has proven to be a highly impactful and positive shift. It has streamlined operations and significantly reduced the complexity and costs associated with using multiple disparate systems. 

Moving to Azure DevOps

As a company, NML organically grew over time from a small group of talented developers working on one or two projects, to a company with 60+ people with complementary skills working on multiple projects over long-term contracts. Organic growth is necessary from such humble beginnings, but it tends to breed bad habits and can blind you to flaws in processes and technologies.

Of course, bad Software Development Life Cycle (SDLC) from organic growth is by no means an inevitable consequence and companies may find that they have issues only in their processes or their technology stack. In our case, however, it turned out to be both!

## Organic SDLC

We have always endeavored to be an agile process company, and we have implemented SCRUM concepts and at times Kanban on our projects. Of course, "agile" being a nearly meaningless buzzword these days, and SCRUM being, at best, very poorly implemented industry-wide, our results varied wildly from project to project.

Our SDLC at about a year ago was roughly some variation of the following:

[EDIT: To be sure, the following describes only some worst-case scenarios, and is not a reflection of the status quo across even most of the projects at NML at the time.]

1. Requirements gathering and analysis
2. Planning and story breakdown
3. Development
4. Testing
5. Bug fixing
6. Deployment
7. Chaos
8. Hotfixes
9. Testing
10. Start at 7, or if lucky, proceed to 11
11. Retrospective bemoaning insufficient or inaccurate requirements, too little time, not enough testing, not enough visibility on work and progress, etc, etc
12. Start at 1

Looking at the list, one can almost choose any number at random, and find problems within that area. Which is exactly what I started doing when it became part of my responsibilities at NML.

In short, we had the following key issues (by no means a complete list):

## No process template

Agile is strong on independent, self-organizing teams, but throughout IT, it seems we interpret that as "figure out what works and just go with it". NML interpreted this no better at times, and we had as many processes as we had projects.

Personally, I dislike processes and structures, as more often than not, they seem arbitrary and aimed at constraining instead of guiding. A guideline is there to help you along a path and sanity check your progress as you move along, without dictating every step and decision. As such, it should be able to serve in more than just a singular context and help problem-solve exceptions.

I have learned that if processes and structures are developed collaboratively, and not dictated, they tend to serve as better understood guidelines. I think one of the main reasons for this is that in order to be collaborative, you need to place good communication high on the list. Goodness knows I have missed that key aspect a couple of times this past year!

## Insufficient clarity

> Working software over comprehensive documentation

The quote above is from the Agile manifesto. I am a fan, really, I am. This particular line, however, has been abused to within an inch of its life, and it generally has come to mean no documentation.

I actually am a huge proponent of super lightweight requirements gathering and little documentation. That is not the same as superficial requirements gathering and no documentation though!

The key to successfully minimize heavy requirements gathering and reams of documentation lie within another line from the Agile manifesto:

> Customer collaboration over contract negotiation

It is imperative to have excellent customer collaboration. I feel that "contract negotiation" here includes requirements gathering, and ensuring that customers' invested involvement is the only way to have any chance of achieving working software over comprehensive documentation.
Poor team cohesion

If you ask most developers what the make up an average-sized agile development team is, invariably the first role listed will be "developer". Now I have not done this exercise, so the following is purely based on my experience as both a developer, a team lead, a project manager and a CTO, but if you ask a tester, or PM the same question, they will give the same answer.

A huge shortcoming at NML was the fact that development teams were developer-centric. Of course, nothing can get developed without a developer's involvement, but I think one can argue that no effective development can occur without at least a project manager (replace scrum master and product owner if you will), developers, testers, and the customer.

It is not good enough to just develop software. The goal should be to develop software effectively. This spans all disciplines within a team, from effective team management to coding and most definitely also testing.

Without excellent cohesion between these disciplines, being effective becomes nearly impossible.

## Stale tooling

The argument could be made that the technology stack and tooling one uses for driving your SDLC is not important for the success of delivering projects, and perhaps it is not. But I think it would be a grave mistake to underestimate the value add of using the right tools for your specific circumstances.

At NML, we have always used Atlassian JIRA. It is a very comprehensive project delivery tool with great community support and loads of useful third-party applications. However, in our context, it was completely counterproductive to our efforts. It was not the right tool for us.

Another example was our testing automation efforts with Katalon studios. In this case, however, there is nothing wrong with the tool, but we were addressing the wrong problems. We opted for tooling over understanding our actual shortcomings.
And now? What now?

Here are how we addressed the above concerns:

- We aligned our project SDLC across the board. We still do not have a "document" that lays down the law, but we collaborated across teams to identify the aspects that work, the aspects that do not, and the aspect that cannot change. We now have a mostly identifiable and familiar process across all our teams.
- We have always been strong on customer collaboration. One of our strengths is that the responsibility for gathering and understanding customer requirements lies with technical team leads and project managers. They form a unit that has both the technical insight and communication know-how to work with the customer and the team. So the major ticket for us to fix with regards to clarity was to specify a minimum set of standards teams should comply with to be able to effectively address requirements. Decent acceptance criteria is a must.
- Our testers are often multi-project team members, and we fell into the habit of excluding them from project planning. The result was that there was very little understanding between the developers and the testers. We addressed this by pulling testers back into planning and making them more integral to the SDLC. The team must identify and add tasks for the tester, which will result in one or more test cases. It improved our overall project delivery visibility and forced us to look at our testing efforts in a whole new light.
- We adopted Azure DevOps. We are a Microsoft technology stack company, and most of our projects end up in the Azure ecosystem. Our project SDLC is much more efficient as we do not need to hop between different tools to push various steps of our SDLC along. Just the efficiency of not having to log into 3 different systems with different credentials is saving us oodles of time and frustration.

## Conclusion

We are nowhere near the end of a journey, which to be honest, should have no end.

I can without a shadow of a doubt say that we are in a much better position than a year ago, and I feel that the teams themselves are happier with how they work currently.

We continue to improve and look out for more opportunities to become more effective. From time to time some old habits creep up but along with the amazing people at NML, I look out for these and re-evaluate our processes again.

NML started small with skilled developers and grew organically to have 60+ skilled individuals on multiple contracts. Organic growth can lead to bad habits and blind spots in processes.

Fixing a Software Development Life Cycle

One thing that I always try to bring home to the developers at NML is this:

> All code changes introduce risk

For some reason, this concept is understood at face value but does not really translate into how we developers approach coding.

I have a couple of mantras I repeat over and over to my teams. Here are the top three:

1. In virtually all contexts, readability trumps other considerations as it improves maintainability.
2. All code changes introduce risk. Code such that when changes are needed, the least amount of code is touched.
3. Do the simplest thing first and build from there. You can always make things more complex, but it is much harder to make complex things simpler.

The biggest side effect of the fact that coding is hard, is that it is also very easy to break things. Seemingly innocuous changes can have unforeseen consequences.

## SOLID = managing risk

Every one of the five principles in SOLID reduces risk.

### Single Responsibility

The more responsibility a module, class or method has, the more likely it is to be touched when change is required. It is just logical. If one piece of code has three behaviors and one of those behaviors needs changes, then all three behaviors are at risk of breaking.

### Open/Close

Allowing implementation to be open for extension and closed for modification hugely reduces risk. If you can implement what is needed by extending an existing class, the only risk is to the new implementation. If you modify a class, especially a base or abstract class, you introduce risk to the class you are modifying, all inheritors and all other code that use it.

### Liskov Substitution

This is a straight forward one: if you cannot reliably use a concrete class anywhere only the interface or abstract is known, you are introducing risk, as you have built-in the ability that your application will fail in specific conditions.

### Interface Segregation

This aligns very closely with SRP and Liskov substitution, and following this principle reduces the risk for the same reasons as the aforementioned.
Dependency Injection

As I pointed out in my article on [unit testing](/blog/2019-12-05-unit-testing-nml/), dependency injection allows you to reduce risk by covering almost all your implementation with unit tests.

Additionally, you can change the behavior of a component by registering a different implementation for a dependency. Your risk is less as no changes are needed in any code that uses the dependency. They reference the abstraction of the dependency, generally an interface.

Lastly, inversion of control removes the lifetime management of your dependencies outside of the scope of your implementation. This hugely reduces risk as you don't need every developer to know the intricacies building a dependency hierarchy in code, and more often than not, getting it wrong.

### Architectural seams

[Architectural seams](https://www.phillipsj.net/posts/creating-seams/) are the border between distinct parts of your system. The data, logic, API, UI, etc are all areas within an application that serve a specific purpose. The purpose of an architectural seam is to provide separation by allowing cooperation without bleeding implementation across distinct areas.

They reduce your code risk by limiting the impact of changes to an area to extend only up to the seams.

### Automapper on the seams

[Automapper](https://automapper.org/) is incredibly useful for many reasons and reducing code risk is one of them. A well-architected system relies heavily upon models to transform and transfer data between layers at the architectural seams.

Using Automapper to perform this duty reduces your risk as changes to model structures are contained in mapping profiles. You might not even need to touch the mapping profile if the affected items do not need explicit mapping.

## Source Control

Source control is a fantastic way to mitigate risk. They provide a history of changes, strategies to control code merging, etc. I do not know of any software company that does not use source control, however, there are some basic measures one can apply to enable your source control system to mitigate risk even further.

### Branch policies

The master branch is your source of truth. It, therefore, needs to be carefully looked after and protected. Policies that limit how code is merged into the master branch is vital to reduce your risk. Various Git vendors, for example, provide different kinds of policies you can apply to protect your branches, and you need to find the right balance between flexibility and freedom, and allowed risk.

### Commit message

There is nothing worse than trying to find a code change in history and having to troll through rubbish comments on commits that give no proper insight into the changes they contain. At NML, we follow the [Karma commit message style](http://karma-runner.github.io/4.0/dev/git-commit-msg.html), and since employing it as a standard, it has made a tremendous difference in our coding lives.

### Pull Request

It may seem odd to some, but there are many companies still not using pull requests for controlling code merges. Pull requests are critical to reducing risk, as they allow other skilled eyes to peruse the suggested code changes and identify problems. Even just putting the obstacle in place that forces a developer to stop and hopefully think about what he or she is about to submit for scrutiny, already reduces risk.

## Conclusion

There are many other areas within the development discipline that effects code risk, and an exhaustive list will make this article impossibly long. The items mentioned here were paramount in minimizing NML and our clients' exposure to code risk, and every company should, at a minimum, apply these to their contexts.

One thing that I always try to bring home to the developers at NML is this: all code changes introduce risk. Here are my top three mantras to minimise code risk.

Managing code risk

I 100% accept that what I am about to say in this post will find dissent in the programming community. That is a good thing as any difference of opinion opens dialog which leads to new information and ideas, and ultimately growth. I encourage people to disagree with me at NML, although as any of the developers will tell you, you need to be prepared to defend your position.

Here is the crux of it:

> As a developer, if you do not have unit tests to validate your work, you have failed at your job, even if the resulting implementation works flawlessly.

## Not just a good idea

My position on this is simple. If a developer tells me that they are done with their implementation, and the answer to "Do you have unit tests?" is "No", then that developer has failed to perform the function that we have hired him/her for.

Unit testing is not just a good idea when appropriate. Delivering a feature without unit testing is delivering less than half of the feature.

I continuously have to drive this point home with our developers (and project managers) and truth be told, I am not sure why. I find it obvious that if I am implementing a required behavior, knowing whether what I implemented works, and being able to let others independently reaffirm that, is well worth the effort.

## Speed is important

A constant objection to unit testing is that it takes too much time and that there is too much pressure to get a feature out. Writing good unit tests can take as much time if not more, as writing the feature itself, so when the pressure is on it should be acceptable to skip unit tests.

It is a nonsense objection because it entirely ignores the resulting development life cycle of the feature. There are two reasons why it is nonsense.

### Going faster by going slow

My own experience on this is that if I spend the time implementing tests that prove the expected behavior of my code, I rarely have to go back to it. When I do not spend time on writing unit tests, I invariably end up having to return to the implementation over at least a number of cycles.

Considering that any returned work breaks the flow of what you are busy with and that it takes away the time of other people on the team, like testers, not implementing unit tests arguably slows down development for any feature.

### Bad estimation practices

It can only true that writing unit tests takes too much time if you view them as a "nice to have", or something that is a good idea, but not critical to the feature. If that is the developers' mindset, they will incorrectly assess the scope and complexity of the work required, and end up under-estimating the time it will take to implement the feature.

On the other hand, if as company and development team you accept that unit tests are part of the feature, absolutely integral to delivery, you must include it in your assessment on the scope of work.

I outright forbid development teams at NML to add a unit test task on their boards. Putting a unit test task on a sprint board is telling me that as a developer you do not see unit testing as part of your job, but that you will do it if you have time since it is "a good idea". Absolutely not acceptable. It is in every way you can imagine part of your job, and you should never have to put a placeholder somewhere to remember to do it.

## Clients do not care

Another objection often sighted is that clients do not care about unit tests and shouldn't have to pay additionally for them.

Again, complete nonsense. Clients do not care about unit tests for their software in the same way that we do not care about cows for our ice cream. We expect the ice cream to be good and tasty, and when it is not we don't blame the cows that produced the milk, we just have a bad experience and never buy from vendor again. Clients want quality software, and when they do not get what they expect, the do not blame the lack of unit tests, they blame the vendor.

If we are honest about what it really takes to implement quality software, of which unit tests form but one important aspect, then we can go a long way towards eliminating bad experiences.

As a software vendor, unit testing should not be an item on a catalog that the client can choose to have or not. The cost to both you as the vendor and the client it too high to even consider that. The cost is definitely more than what it would be if unit testing is just par for the course of development, and considered upfront.

As a vendor, if you have a client that willingly chooses fragile, unreliable software because it costs less up front and will be delivered faster, then you absolutely need to refer that client to another vendor. What they're really saying is that they want to pay less upfront, and will then, later on, insist that you did not deliver what was agreed on, as they do not have properly working software.

As a client, if you have a vendor giving you the option to skip unit tests, go somewhere else for your software. What they are really saying is that you might get your software fast and cheap, but then after you are committed, you will have to spend at least three times more than you budgeted for and wait twice as long to get the software you want.

## Conclusion

Writing code is not an easy endeavor and developers, even the smartest ones, will make mistakes while they develop. The best way to reliably minimize mistakes is to write simple concise code that verifies the intended behavior repeatably, aka unit tests. Unit tests are not additional work or additional cost, they're integral to the development effort. Unit tests should be invisible as an item of work since they are part of the work.

That means that writing unit tests is your job in every way that writing code for a feature is.


As a developer, if you do not have unit tests to validate your work, you have failed at your job, even if the resulting implementation works flawlessly.

Unit testing is your job

Unit testing as a concept is simple. Write code to test code. It seems, though, that everybody forgets one fact about coding: It is really hard!

I do not think it will be a stretch to say that most production codebases lack even a decent number of unit tests. Further, I am pretty sure a lot of those unit tests tend to be flaky and fragile and at times less than useful.

Plenty of articles from people way smarter than I exist on this topic, but I would like to give some insight into the way I encourage our developers to write unit tests at NML. We did a on this topic, but could not get to as much detail in the session as I would have liked. My previous article on [unit tests](/blog/unit-testing-is-your-job/) pointed out the importance that unit tests should play in a developer's day-to-day job. This article gives outlines essentials on how to really get past those hurdles that make unit testing hard.

## It is what I do, not how I do it

The first big mistake is to test how the target code works. The key insight is to test specific behavior in the code. The what.

The simplest strategy is to start at the top, and read through your code, identifying key entry points, and specific behavior.

I define behavior here as:

> A single logical execution path from a public entry point up to where it returns or throws
 
``` javascript
public class Dodo
{
  private IHabitat _habitat;
  public Point Postion { get; }

  public Dodo(IHabitat habitat, Position initialPosition)
  {
    _habitat = habitat 
      ?? throw new ArgumentNullException(nameof(habitat));    
    Position = position;
  }

  public void Fly(Direction direction)
  {
    if (!CanStillRun(direction))
      throw new EndOfTheLineException(direction);

     Move(direction); 
  }
  
  private bool CanStillRun(Direction direction)
  {
     return _habitat.HasSpaceLeft(direction, _position);
  }

  public void Move(Direction direction)
  {
    // Don't be silly! Dodos can't fly. 
    // They just sit around and do nothing.    
  }
}
```  

The trivial example class above will have several specific behaviors, and if we test each of those, then we will get 100% code coverage, and we will have tests that catch issues not only when somebody changes the codebase, but also when they change expect behavior.

Reading from the top, there are declarations, which by themselves are not testable. Then we hit the first entry point, which of course, is the constructor. Since we are at an entry point, we have to start identifying behaviors. The very first line in the constructor is doing something, and in fact, thanks to C# syntactic sugar it is doing two somethings.

The first thing it does is check if the habitat variable is null, and if it is it throws an exception. That is one complete behavior because the throw statement will exit the entry point. You must, therefore, write a test to cover that.

``` javascript
public void ConstructorThrowsWhenHabitatIsNull()
{
  Action construct = () => new Dodo(null, _initialPosition);
  construct.Should().Throw<ArgumentNullException>("*habitat*");
}
```

The above tests use the [FluentAssertions](https://fluentassertions.com/) testing library, which is excellent, and I highly recommend it. Ignoring the syntax though, notice that the test is short and that it checks for only one behavior, the throw clause.

After we have written and run our test, we start at the same entry point and follow the alternate path from that line onwards. The next behavior is the assignment to the `_habitat` field. Execution will not stop there, so we continue reading. On the next line, we assign the Position property, which is still not exiting. Lastly, execution will hit the end brace `(})` of the constructor, and the entry point is exited. That is a complete behavior and we, therefore, need a test.

``` javascript
public void Constructor()
{
  var dodo = new Dodo(_mockHabitat.Object, _initialPosition);
  dodo.Should().NotBeNull();
  dodo.Position.Should().Be(_initialPosition);
}
```

The test above verifies that the constructor will run to completion and return a non-null instance of a Dodo, and also that any public items affected by the behavior are what we expect.

The key takeaway here is that to verify the success or failure of a behavior you have to not only check the result, but also any side-effects.

This article will be way too long if I continue with the example, but I think the above serves to show how to go about it. Using this method, the next behaviors are:

- The Fly method throws an exception when `_habitat.HasSpaceLeft returns` `false`
- The Fly method executes and Position stays the same when `_habitat.HasSpaceLeft` returns `true`

> Unit tests should verify behavior, not implementation

## Interfacing Solidly

If the "D" from the [SOLID](https://en.wikipedia.org/wiki/SOLID) principles (dependency injection) is not at the very core of every class you design and write, you will not be able to write successful unit tests. It is just that simple. Your unit tests will be fragile, they will be unreliable, and they will cause massive maintenance headaches as unrelated tests to the actual code change will break in a cascading fashion.

At NML I insist on a DI mindset. Effective dependency injection requires interfaces If you keep to injecting only interfaces to all your classes, you will have a pleasant time writing unit tests for them. Yes, you will have a lot of interfaces that potentially have only one concrete in your codebase, but it is worth it just from the benefits you gain from being able to test your code in complete isolation.

If you are using a dependency from a third-party library that does not provide an interface you can mock out, wrap it with the proxy pattern. Ideally, the only classes you should be unable to test in isolation should be proxies. Ideally... ;-)

> Unit testing requires Inversion of Control

## Mock and Verify

The previous two tips are integral to get the most out of libraries like [Moq](https://github.com/moq/moq4), [RhinoMocks](https://hibernatingrhinos.com/oss/rhino-mocks), and [FakeItEasy](https://fakeiteasy.readthedocs.io/en/stable/). The important thing to remember about mocking dependencies is that you only mock what you need when you need it.

When you follow the "read from top to bottom" approach outlined above, you will be forced to have a mock version of all the target class dependencies by the time you completed all the behavior tests for the constructor. At that stage, they should not be configured to return or respond to anything that was not required in the constructor.

In our example above, I would only add a response configuration for the IHabitat.HasSpaceLeft method once I identify that it is needed to test the behavior(s) passing that method call.

Unfortunately, a lot of developers tackle writing unit tests a lot like the tackle writing classes. They try to think of as a whole and plan out fields and methods at the start.

Another important thing to remember is that you must verify that methods and properties on dependencies were called with the expected arguments. It is part of the behavior to call a dependency with specific data, which might undergo some kind of transformation.

> Unit tests should be discovered by investigating behavior

## Conclusion

These three essential concepts, along with accepting that [unit testing is your job](/blog/unit-testing-is-your-job/), will improve your code coverage, improve your code quality, and prevent you from chasing down elusive problems later that would have been caught earlier with good unit test coverage.


Unit testing as a concept is simple. Write code to test code. It seems, though, that everybody forgets one fact about coding: It is really hard!

Unit testing at NML

Up to now, NML has followed what everybody in IT would generally recognise as a "sensible" approach to software diagramming. Mostly it consists of drawing blocks with names and connectors trying to represent some logical or physical system layout. I've been working at structuring our approach over the last couple of years so that there is more project alignment and that we can extract more value from our efforts. As you'll see, we did end up at what I would consider a reasonable system, but it has some flaws which we are now correcting by using the C4 modelling paradigm.

NML design strategy to date
---------------------------

The following describes the NML style of modelling we've used until recently.

### High-level overview

The diagram type is a depiction of the various logical concepts and ideas that would portray a non-technical view of the system and its integration dependencies. Boundaries with blocks and lines show some kind of connection between elements. The blocks would have a name on them to indicate function or purpose.

![High-level overview diagram](https://d33wubrfki0l68.cloudfront.net/70ab6a999556280ca231ab179ad82172de73af67/17933/static/images/blog-overview-component-overview.png)

The idea behind this diagram was to give some indication about the system's interactions in as non-technical a fashion as possible. Our designers would often convert these into beautiful presentation worthy pictures that clients could use in their slide decks.

### Infrastructure

This is where most of our design and architecture work would go into. This diagram contains a lot of technical information and describes the system components, the target infrastructure technology, and how they communicate.

![Infrastructure diagram](https://d33wubrfki0l68.cloudfront.net/3df2b8bf9e3265a3e9c5a703c23f14e47eb44f19/eb237/static/images/blog-overview-infrastructure.png)

The purpose is here is to be able to show technical people how the system will physically look and interact. It is very information-dense and you need some prior technical knowledge to understand what is going on.

### Technology stack

Even though a large part of the target technologies is represented on the infrastructure diagram, it normally doesn't cover all technologies needed to build any specific part of the system under design. We, therefore, produce a technology stack diagram that conveys more of that information.

![Technology stack diagram](https://d33wubrfki0l68.cloudfront.net/50001564fc43b4a0f38b7e100026d484ed8b22ec/712e6/static/images/blog-overview-tech-stack.png)

### Other

From time to time we will need some other types of diagrams to relay more technical information. For example, we will draw a UML sequence diagram for sub-system interactions that needs some more clarity or thought put into it.

For messaging systems, we will sometimes diagram messaging and endpoint diagrams to help understand complicated messaging environments.

![Message-flow diagram](https://d33wubrfki0l68.cloudfront.net/17c5e94c108c8b1f30761992c0a00d33e8f5a7b7/2497b/static/images/blog-overview-messageflow.png)

Such lower-level diagrams we only do when more clarity is needed and the effort involved can be justified. It does not help to spend time on drawing up a diagram that doesn't provide useful additional explanatory information.

Need for change
---------------

This approach to systems and architectures diagraming works and has been effective for us. I've certainly seen worse! But, I'll admit to drawbacks that I either didn't realise was there or didn't know how to resolve.

### Too much or too little information

What I mean by "too much or too little information" is that there is no real guideline about what information is important on the diagram and what isn't. So some aspects can be too technical, and in the context of what you are trying to convey, will add information without enhancing your understanding of the diagram. At the same time, often on the same diagram, you can find elements with a single word name only, which without some prior or specific knowledge would be useless to most people reading the diagram.

There is also a reliance on iconography to relay important information on the infrastructure diagram. Without knowing what the icons mean one can very easily miss that it is important information and just accept it's there for aesthetics.

_Diagrams should contain plenty of information, but only information that is relevant to elucidating the purpose of the diagram's existence._

### No identified target audience

The high-level overview diagrams outlined above try to be everything for everybody. Clients may like it because it looks nice in a presentation, but the way it was generally structured was also trying to give technical people some information at the same time.

As for the infrastructure diagram, they are very technical and requires quite a bit of understanding of infrastructure. Unfortunately, they were also used to discuss the system with clients, non-technical people, or technical people with a different skillset, and required a lot of explanation. Because the one does not follow logically from the other, you had very little to tie the diagrams together to help you guide the audience through the designs.

_Having a specific target audience in mind will guide you in what information is relevant and important for the diagram to effectively communicate its purpose._

### No commonality

The aforementioned diagrams have no base concepts or notations in common. They each follow their own practice and notation and going from one to the other causes you to reset your mind restart the learning process about the elements on the diagram.

_Common notation makes creating and understanding diagrams a lot easier._

### No exploratory power

Each diagram is reflecting all of the system architecture at some level, and none of them helps you in defining the other diagrams. They may cause you to refine, but they don't guide you towards a deeper understanding of the solution step by step. You solve the system architecture by working on all of them.

_Being able to use diagramming as an investigative tool to delve into more complex areas of a system architecture helps in understanding the problem you are solving more completely._

Why C4 modelling is our new strategy
------------------------------------

I discovered the C4 modelling paradigm while researching how a more effective diagramming tool. I've been recommending diagrams.net (aka draw.io) for creating the diagrams described above. The problem is that diagrams.net is bad at creating UML diagrams, and I had some of my team working on sequence diagrams for some complex designs they were preparing for. One of the team members was showing me a diagram he was still working on, explaining that he'll redraw it in diagrams.net when he is done, but that the tool he was using was just faster to create and modify the diagram with.

The tool in question being [PlantUML](https://plantuml.com/). I try to never have any sacred cows when it comes to technology as there is always something better around the corner. I support being more effective at how we work at NML above "toeing the line". I started reading up on PlantUML, and as part of their online documentation, they mention [C4 Modeling](https://c4model.com/). That led me to watch [Visualising software architecture with the C4 model - Simon Brown, Agile on the Beach 2019](https://youtu.be/x2-rSnhpw0g). It is worth watching and Simon Brown hits the nail on the head with regards to the lost art of software architecture design.

His conceptualization of how to model systems architectures is simple, easy, and most importantly: useful. Visit the [C4 Modeling](https://c4model.com/) website for a more comprehensive overview. The biggest advantage of practising C4 modelling is that it automatically guides you towards the solution and architecture you need. Your start from a zoomed-out perspective, and then drill in deeper and deeper, interrogating each part on its merits and solving for what architecture is needed to support the system.

C4 modelling in short
---------------------

For an in-depth and much better explanation of the abstractions, notation and diagrams in C4, use the links above. The following is only an introduction.

C4 stands for the for 'C's found in the main diagram types:

*   **C**ontext
*   **C**ontainer
*   **C**omponents
*   **C**ode

### Context Diagram

The [context diagram's](https://c4model.com/#SystemContextDiagram) only purpose is to frame your system in relation to supporting systems, data sources and users. Nothing technical is described in it. Recreating our overview diagram from above as a C4 context diagram will yield something akin to the following.

![Context Diagram](https://d33wubrfki0l68.cloudfront.net/c48fa98be63e254fcf4ba606c7780ba98ba0ea0a/8bc82/static/images/c4_elements-context_diagram___investment_portal.png)

Note the copious use of text on the diagram. Information in an understandable way is the essence of C4. More textual information is not obscuring the diagram, it enhances the value of the diagram.

### Container Diagram

[Container diagrams](https://c4model.com/#ContainerDiagram) take the context diagram and zoom into the system we are architecting. It breaks the single system block into execution and data storage units, containers in C4 parlance, that will be deployable in some fashion. It also starts to shed light on the technology that will be used.

![Containers diagram](https://d33wubrfki0l68.cloudfront.net/79234f8ce3e42f106f55014a20ef9ce927a425a6/8967c/static/images/c4_elements-containers_diagram___investment_portal.png)

The system is now represented as being made up of distinct parts, that include the target technologies and a description of the container's purpose. It also shows in more detail now where interaction with external users and systems occur.

### Component Diagrams

The next level deeper expands the relevant details of one of the identified containers. The exact detail needed on this diagram is more open to interpretation, but important structural parts to the make-up of a container and their interactions are what one wants to capture.

![Portal GraphQL API component diagram ](https://d33wubrfki0l68.cloudfront.net/cc3799d7ef8869d228aa96a0e4c11ed633eaa5bc/512fa/static/images/c4_elements-component_diagram___portal_graphql_api___size_15__color_gray_description_of_the_component_being_modeled__color___size_.png)

From the example diagram, you can see the most important aspects of the container that needs to be thought of. Some of the elements identified on the context and container diagrams are also not present here since they do not interact with the container.

Here I just show the API component diagram. There will be an equivalent Portal Web Application diagram too.

### Code

In the video linked to above, Simon Brown recommends that you don't delve further into code diagrams unless required. From our own experience at NML, I agree with that viewpoint. You do not need to have every aspect of your system diagrammed out. The value successive level adds do not increase in step with the effort and difficulty involved in creating them. That doesn't mean that there aren't circumstances where code diagrams are justified.

I won't show code diagrams here as they are in general UML diagrams, like sequence or class diagrams.

### Additional

There are 3 more diagrams defined by the C4 model which are optional but can be useful to clarify certain design aspects of the system. I won't go into detail here other than list them:

*   System Landscape diagram
*   Deployment diagram
*   Dynamic diagram

Read up on them and experiment with them to find where they help your design process.

Conclusion
----------

C4 modelling defines an approach to system architecture that is both informative and useful in helping with the architecture endeavour. Delving into successive diagrams from a more abstract view guides you into thinking about the interactions and solutions required to design the system. NML is pivoting toward using C4 modelling using PlantUML and the feedback from the technical teams thus far has been very positive.

Up to now, NML has followed what everybody in IT would generally recognise as a "sensible" approach to software diagramming. Mostly, it consists of drawing blocks with names and connectors to represent some logical or physical system layout. 

Architecture Modeling at NML

It takes time to learn any platform, and Azure is no different. Azure is generally speaking quite easy to use, belying the complexity and hidden pitfalls one might encounter when provisioning and managing resources.

In this article, I will try to give some practical advice from what I have learned during our [NML](https://nml.co.za) Azure journey.

## Find your happy place

The first thing that will save you loads of pain and frustration is to choose a region and stick to it. When provisioning a resource you can select the region you where you want the resource to be hosted. There is no "default", and so at times, the default selected value in the region dropdown will be different from what you previously selected. It has often happened that we have had, by accident, resources and resource groups in widely different regions.

The choice of the Azure region you want to target will depend on your precise criteria, but generally, you will want to choose the region that gives you the least amount of network latency. For South Africa, that used to be West Europe or North Europe. You also now have West UK and South UK with comparable latencies to the prior regions. However, at the time of writing, Northern South Africa is generally available, with most of the Azure resources one needs for a common software system. Southern South Africa is running and used for regional replication and backups, but not generally available yet.

## Birds of a feather

NML is a services company and we host our development, testing, user acceptance criteria, and production environments on behalf of our clients on Azure. Over time we learned that provisioning a dedicated subscription for a client or project, and then grouping resources by environment in the subscription works best.

By dedicating a subscription per project or client you make billing much easier, as Azure is able to give you cost per subscription at a glance. It will also help with managing costs as you can setup cost alerts and budget on a subscription.

Grouping resources by a target environment is essential to configuring secure infrastructure for a project. Probably the most important and helpful tip here is to find a naming convention and stick to it. It will make your maintenance much more bearable.

At NML, we use the following convention: `<PROJECT_ACCRONYM>-<ENVIRONMENT>`. For a project, say AdventureWorks, we would have the following resource groups:

- advwrks-dev
- advwrks-qa
- advwrks-uat
- advwrks-prod
- advwrks-shared

Azure costs can add up quickly if one is not careful, and so at NML we generally have a shared resource group for our development and testing environments with resources that can be shared and reused. Production is always isolated to ensure a good security posture. The resource types that are most responsible for ballooning costs and that can be shared readily are:

- App Service Plans
- SQL Server
- Cosmos DB
- Redis
- ServiceBus & EventGrid
- Storage Accounts
- Virtual Machines

## RBAC properly

Role Based Access Control (or RBAC) is the heart and soul of resource security on Azure. When hosting a solution for a client, you need to ensure that you protect their interests as best you can. With RBAC you can go along way towards ensuring that goal.

RBAC works by assigning users one or more roles on any particular resource group or subscription. Each role has a strictly defined set of allowed operations that can be performed, and any action that falls outside will be denied.

The most import piece of advice here is to assign access via Azure AD security groups. Assigning roles individually quickly turns into a management nightmare. By leveraging on user security groups, you can easily swap and change user access by only having to update the security groups they belong to. You can then assign the relevant security groups on a resource group level to the roles that are needed. As far as possible, do not assign subscription wide roles to any user or group. That is because, at the time of writing, Azure does not have `deny rights` configuration. Roles added on a subscription level will, therefore, apply to all resource groups and resources on and inheritance basis.

We generally make a distinction between development users and production users and will, therefore, have at least two sets of security groups. The groups are named for the project or client and the role that they will be assigned to. For example, for the Contributor role on the AdventureWorks project, we will have the following security groups:

- advwrks-contributors
- advwrks-prod-contributors

There will be similar security groups for each role to be assigned. Examples of roles we generally have are:

- *-contributor
- *-key-vault-contributor
- *-key-vault-reader
- *-web-contributor
- *-monitoring-contributor

Using this scheme allows us to configure developer access to the development environments and to have restricted access to production environments and only temporarily assign access where and when needed.

## The help you need

Azure has some built-in features, some for pay, that is essential for running deployments successfully on the platform.

### Security Center

Security center helps in identifying and rectifying potential security risks to your resources. It will identify various platform configuration issues that you can improve, for example, configuring firewalls on key resources like Azure SQL Server, Key Vault, etc. It will also identify configuration on virtual machines that need attention.

Review Security Center recommendations frequently. Not everything is practical or applicable, but most of it is gold.

### Advisor

Advisor is there to help to get the most out of your resources. It checks and recommends improvements on the following:

- High Availability
- Security
- Performance
- Operational excellence
-  Cost

Keep checking back in with Advisor, as it will highlight areas in your Azure ecosystem that need attention.

### Cost Management + Billing

Here you can, at a glance, see your current monetary exposure over your all Azure resources. You should configure budgets and alerts on subscriptions and/or resource groups. It is a rather unpleasant feeling to receive a bill at the end of the month that is hugely inflated because of a development mistake or infrastructure configuration issue that could have been prevented with a timeous alert.

## General

### App Service Plans

Be careful of racking up a slew of underutilized App Service Plans. They are mostly used for Web Apps, Logic Apps, and Functions, and should be shared. Some features are only available on higher-priced tiers, and over time you might realize you are paying more than is necessary because App Service Plans had been scaled up to unlock some needed features.

### Cosmos DB

Cosmos DB is a wonderful piece of technology, but its costing is a little like black magic. It is not priced by what you use, but rather by what you think you are going to use (reserved resource model). Be conservative when you configure Cosmos DB, and scale up once you have data indicating that you need to reserve more resources.

### Naming conventions

Azure has a wonderful search feature to find resources quickly. A standard, practical naming convention across all resources (not just resource groups) will save you oodles of time. It is much better to have an `advwrks-dev-frontend` web app in the `advwrks-dev` resource group, than to just have `frontend` in there. Make sure everybody that has permissions to create resources follows the scheme as closely as practically possible.

### Conclusion

Azure is a tremendously useful and pleasant platform to work on. However, one can safeguard your experience (and wallet!) by implementing and following some basic guidelines like that described above.


It takes time to learn any platform, and Azure is no different. Azure is generally speaking quite easy to use, belying the complexity and hidden pitfalls one might encounter when provisioning and managing resources.

Practical Azure

> Any sufficiently advanced technology is indistinguishable from magic.
 
The best-known and most widely cited of Arthur C Clarke’s three laws.
 
Another axiom relevant to the world of software development and AI is this:
 
> Bullshit in, bullshit out.
 
Those two truisms should be given in an AI-first world. So, what will help a software development company like NML differentiate itself from its peers in the coming years?
 
Let me give you some of my thoughts and thus introduce an AI-first series of posts I’d like to publish.
 
Sixteen years ago, I launched the software development house NML. In 2016, NML birthed [Atura](https://atura.ai), an AI-first client service chatbot. Doing so thrust me into the thick of the rapidly evolving world of AI, particularly robotic process automation and natural language processing, well before AI was a hot topic in public discourse.  
 
The advent of AI-driven code generation is creating a major shift in software development. It is forcing my team at NML and me to rethink the skillset we need. Over the next three years, we will disrupt ourselves from the inside out, leveraging the accelerated learnings gained through Atura.
 
> Do more with less.
 
The CTOs and CIOs in our client base are already asking for this: essentially higher sprint velocities using AI-driven code. What we cannot bypass if we want to avoid producing bullshit and instead create magic is the human interaction required to refine and implement AI-generated code.
 
Interacting with LLMs and using retrieval-augmented generation (RAG) off domain-specific documents will become a basic, commoditised task. NML and Atura’s differentiators, I believe, will be the ability to build client-specific machine-learning models, refine autogenerated code, and trigger complex and dynamic language flows that interact with operational systems—that is, don’t just retrieve basic textual answers.
 
For these reasons, my last two hires have been actuaries with little understanding of designing and writing commercial code. They’re learning fast with a little help from their AI friends.
 
These are interesting times, and adapting to a changing landscape is becoming more critical than growth under rapidly ageing business models and structures. I’m enjoying the change.
 
Follow me as I go deeper into how we are rethinking our software business at NML in my upcoming posts.



The founder of NML details the transformative journey of integrating AI into software development, leveraging AI-driven tools to meet client demands for efficient and refined code solutions.

NML Articles & Thought Leadership

Transforming Software Development at NML