.NET Software Architect

Platform or technology stack specific modifiers on the title of Software Architect are common. Most software architects know that the platform, like a framework, is an interchangeable implementation choice and not really part of the software architecture (see my post entitled Practical Agile Software Architecture).

Why the distinction then? Two reasons:

  • Architect as Implementer  - Many software architects are involved in guiding and contributing to platform specific implementation which requires specialization that is not specific to the architecture itself. I prefer this combination.
  • Platform Specific Language - The platform specific software architect may be most comfortable or even required to produce artifacts that adopt the vernacular of that platform in order to make those artifacts more easily consumed by the implementation team.

The most common platform and implementation specific language elements in architecture artifacts replace the more generic terms of module, component, and software. Here’s an overly simple conversion table that I have found helpful for Java and .NET.

Architecture Generic Java .NET
Module package with public classes defining "port" and  sometimes an entire jar namespace with public classes defining "port" and sometimes whole assembly
Component sometimes jar only but usually whole container or daemon sometimes an independent assembly but usually a single process/web app
Software (physical allocation) app servlet engine for container or independent daemon IIS web app for one or more components or an independent Windows service

.
Connectors are generally common across these stacks, with a few exceptions such as WCF and JAX. More often connectors are literally specified as a SOAP or REST or even a custom TCP based protocol. Message based connectors are very often technology specific, indicating the specific message queue but be careful to avoid limiting your architecture by specifying implementation choices. The implementation choices should be, as much as possible, left to the design and implementation team effort.

The majority of my implementation experience has been in the .NET stack. But software architecture should be the same across implementation stacks. Of course, there may be some things easier said than done in a specific platform and technology stack, and that may have an impact on your software architecture choices, but minimally so.

Practical Agile Software Architecture

Ask software professionals what software architecture is and you will get many different answers.

In the past I have worked as a software architect and development lead on a variety of projects and teams. Two years ago I joined a larger software development organization as an individual contributor, and for the last eight months I’ve been the sole engineer assigned to create a very large in-memory graph data service that provides sub-second traversals across tens of thousands of edges amongst several billion. It has been a fun and successful project, but lately I’ve been thinking more and more about software architecture.

I’m sure that millions of words have been written on the subject of software architecture. I have read of them. Most recently I’ve been perusing two tomes on the subject: Software Architecture Foundations, Theory and Practice (Taylor, et al) and Software Architecture in Practice - 3rd Edition (Bass, et al). The latter is quickly becoming my favorite, but both of these are exhaustive academic textbooks, so most software professionals would find it impractical to put them to good use. Even so, I recommend them to you.

So what do I mean by “practical agile software architecture” and how can it be used by an agile software development organization? That is the question I will attempt to answer here. Distilling some of my reading through the filter of my own experience, I offer the following thoughts on the matter.

Principles of Practical Agile Software Architecture

  • Architecture is part of the product or a product dependency – Architecture should come first. Any large and complicated software project should have a architectural artifacts (see below) sufficiently defined to guide product backlog story definition to seed and sustain ongoing implementation with minimal risk of disruptive architectural changes.
  • Architecture stories go on the backlog – Architecture stories are generated from the stakeholder/view matrix (see below). Stories may repeat by adding detail to or modifying existing artifacts. Modifications should therefore be taken carefully considering the implementation changes that may be required.
  • Architecture story implementation produces artifacts (scenarios and views) – The architectural scenarios and views (Bass) include the definition of non-functional quality attributes such as security, reliability and performance. These artifacts document the architecture sufficient for the implementation team as well as stakeholders.
  • Architecture quality attributes should be measurable – Simply declaring that the application must be fast is not enough. Quality attribute definitions, as one type of artifact (see scenarios below), must produce measurable, observable, testable indicators.
  • Architecture artifacts evolve iteratively – Each iteration should produce a useable architecture, sufficient to inform stakeholder decisions and guide implementation. This does not mean that the architecture is never revisited. Architecture should be a regular part of every iteration, even if the story is simply to review some part or the whole of the architecture that is relevant to other stories being worked on during that iteration.
  • Architecture change can affect product backlog – Architecture stories that result in a modification to an artifact will generally produce one or more changes to the product backlog in order to accommodate the modification in product implementation. Care should be taken to communicate each new version of the architecture to relevant stakeholders and the implementation team.
  • Architecture complexity should be decomposed – In multi-team multi-service multi-product development organizations, it may be useful to create a centralized architecture team that defines and develops higher level architectural views upon which implementation teams take a dependency. Changes to the central architecture may produce changes to a service or product’s architecture related stories on their own backlog. As scrum of scrums can help to decompose more complex projects, so can the same approach be used to break down the complexity of the overall architecture to ensure agility.

Architecture Artifacts and Views

Documenting an architecture can be challenging. Some documents are produced as an overview. Some with varying levels of detail. Much of this depends upon the extent to which the architecture is complete and the intended audience for the specific view. Whether you call these documents a “view” or a treatment or a physical or logical or quality requirements document, the result should be the same. These documents should convey as concisely as possible the information needed to by stakeholders and implementation teams to make decisions.

These are summarized from Bass with my own particular spin.

  • Qualities Scenarios – There are seven primary non-functional software qualities: security, availability, interoperability, modifiability, performance, testability and usability. These should be well defined with concrete scenarios specifying stimulus source, stimulus, environment, artifact, response and acceptable response measures. Here’s a summary example for each of the seven qualities.
    • Security – A user (source) attempts to view private information (stimulus) in the patient records systems (artifact) on the beta testing system (environment) and an audit trail is maintained (response) and the attempt is prevented and reported (measure).
    • Availability – A heartbeat monitor (source) receives server unresponsive status (stimulus) on a web service (artifact) in production operations (environment) and informs the failover system to take traffic (response) and no downtime is recorded (measure).
    • Interoperability – Our patient billing system (source) sends account to collections (stimulus) to the collections system (artifact) in the testing system (environment) and a test letter is sent (response) and the test letter queue increases by one (measure).
    • Modifiability – Developer (source) is required to change a data source (stimulus) on the records repository (artifact) in the source code (environment) and makes the change with a unit test (response) and completes the task in three hours (measure). 
    • Performance – A user (source) save changes to his profile (stimulus) in the company intranet (artifact) on the intranet (environment) and the change is displayed (response) and the change takes less than two seconds (measure).
    • Testability – An automated unit test runner (source) executes a unit test (stimulus) on the code (artifact) in the test server (environment) and the test passes (response) with 85% code coverage (measure).
    • Usability – A user (source) adds a widget to his blog (stimulus) on the admin page (artifact) in the production system (environment) and is taken to a page with the widget activated (response) with fewer than 3 modifications (measure).
  • Module View – In the module view, design principles such as separation of concerns and loose coupling help to define boundaries around responsibility sets. Often a module is a separately compiled unit (e.g. a .NET assembly DLL).For example, the data repository module depends on and implements the data repository interfaces module which provides data models and the interface definitions for persisting those models. The data repository module can be replaced when a decision is taken to move from one database server to another.
    • Elements – module = implementation units (sets of responsibilities)
    • Relations – is a part of X, depends on Y, and is a Z 
    • Constraints – visibility and availability of module
    • Usage – implementation blueprint, impact analysis, requirements tracing, information design, users stories and use cases
  • Component & Connector View – Components and connections define logical processing units (processes or sub-processes) or data stores and their ports (sometimes called API) for connections to connect to. This could be a web service and the port (not TCP port) that defines the external boundary of that processing unit. A connector may me a message queue pushing and pulling messages or a browser connecting to a RESTful web service.
    • Elements – component = processing unit or data store, connector = paths of interaction (external API and use of same)
    • Relations – attachment = connector connected to a component port, interface delegation = a connector between compatible ports
    • Constraints – components attach via port only to components and vice-versa, never to each other
    • Usage – illustrate how the system works, define communication boundaries, guide implementation and design structure, and guide establishment of quality attributes for each component
  • Physical Allocation View – Define the software that will run on each part of the physical deployment in each environment.
    • Elements – software = what runs on each part of the environment, environment = where software is hosted and on what
    • Usage – assists reasoning about quality attributes, distribution of work and teams, concurrent access to versions of the software, and the form and mechanics of software deployment
  • Qualities View – A quality view document helps to correlate specific qualities and their scenarios with respect to the following:
    • Security – define components and behaviors that have an impact on security and how security risks will be mitigated and prioritized.
    • Communications – document how components will communicate, what networks channels and internal and external systems will be involved in data transfer, and how quality of service (QoS) will be maintained and how communication interruptions will be managed
    • Exception / error handling – define how errors will be detected, reported, monitored and resolved
    • Reliability – define how timing, integrity and other quality measures will be recorded and monitored
    • Performance – establish traffic load expectation and handling patterns, latency and system and network metrics

For more complete details on how these views may be composed, I recommend picking up a copy of Software Architecture in Practice as previously mentioned.

Stakeholder View Matrix

Because the number of possible views and scenarios with varying levels of required detail can overwhelm the architecture backlog, I endorse the Bass recommendation of the stakeholder/view matrix. I’ll try to summarize it here.

Create a matrix of stakeholders, including implementation and testing roles, with common architecture views and qualities. Let’s assume you have executive, product manager, implementation and testing stakeholders. And you have seven qualities and a minimum of four views. This gives you a four by eleven matrix.

For each cell in the matrix enter a level of detail word (none, overview, moderate, high) and a priority number between 1 and 10. Use this matrix to identify artifacts that need to be produced first and what level of detail is required for the first, second and third iterations. This exercise will help you identify the most important architectural stories for your backlog and prioritize your work on the architecture.

Thoughts on Architecture and the Role of the Architect

Much of what a software architect is often required to do is not, strictly speaking, architecturally related. But if an architect wants a team to be successful at implementing the software, she or he will take special care to incorporate these things into their regular work.

  • Patterns and Frameworksarchitecture is NOT a framework. In fact, a framework should be able to be swapped out without really having to change the architecture. Frameworks are tools and as such should be carefully chosen for their implementation multiplier capabilities as well as their simplicity and adaptability. The same is true for implementation patterns. Developers who are guided to select appropriate implementation patterns by being provided prototypes and samples can be far more productive and will produce much more maintainable code. The effort invested by the hands-on architect in these will yield handsome returns.
  • BDD and TDD – architects often wear the design hat as well and when doing so, they should adopt Behavior Driven and Test Driven Development. Read the linked content. It will really help simplify and clarify your user stories, use cases, and test designs. Of course, most design is driven by functional requirements which can affect the architecture in order to support the behaviors defined by the functional requirements. The software architect is appropriately involved in gathering and understanding these requirements. And breaking them down by behavior driven forms is an ideal way to fully understand and document these requirements.
  • UML and Other Modeling Languages – there are many tools available to create diagrams and other artifacts that may help you communicate your architectures and designs. A word of caution. Unless your audience is familiar with the notation and the meaning of the symbols and shapes you use, you need to provide a key with sufficient detail that a less familiar reader can understand what it is your are trying to communicate. If the diagram uses too many abstractions, the reader, even a seasoned software engineer, may have trouble understanding your meaning. And when stakeholders and implementation team members do not understand it, they will not always ask. Most of the time they will either ignore or or make erroneous assumptions that will bite you in the tender flesh later.
  • DevOps and Infrastructure – one of the things that can kill a great architecture and implementation is the lack of sufficient means to build, test and deploy, and roll back when necessary, in an automated fashion. A great DevOps team can make or break your large software development organization. And if you have the necessary operations monitoring and SLA failover triggers enabled with redundancy, you can maintain a very high level of service and reliability. A software architect’s input into the creation and improvement of these is critical to success.

Conclusion

Software architecture is not necessarily easy in part because we often make it more complicated than it need be. It is also true that we rarely define it well within an organization. Many organizations hire and promote to the position of software architect with the expectation that they will be an experienced software engineer who has picked up on what works and what does not and will help lead a team to success. Many experienced software engineer’s make this transition and learn the craft of architecture well. Some do not.

Some software architects spend very little time defining and refining the actual architecture of a the software. Instead they spend far more time chasing down design flaws, resolving thorny implementation issues and untangling behaviors that are at odds with business requirements. And yet, had the architect spent sufficient time and energy producing concise and precise architecture artifacts discussed in this post, continually improving them, reviewing them and coordinating their impact on implementation backlogs, many of the problems they spend so much time on would have been avoided.

I know you have differing opinions. Please share them here.

Origins of My Inner Geek

In elementary school, I loved being an AV (audio-visual) library assistant and running the mimeograph machine. I knew all the tricks to getting that film strip projector to work. I was an expert overhead projector operator. And I could thread a 16mm projector faster than anyone.

I was the master of my domain. I was a geek before the pocket protector became the defacto standard geek identification badge.

Fast forward to a time when I had suppressed the geek within to become a lawyer. I even took an English undergrad degree. I was married when I received my Bachelor of Arts, so I’m not sure it counted. But they gave it to me anyway. Then having had a chance to work for a lawyer for a while, I realized I could never be a lawyer—I hated the work too much to study for the LSAT. And so I became a tech writer. What else.

commodore_pet4016_3And a few years later, while I furiously scribbled notes on my legal pad, the ancient primitive predecessor to the iPad, I overheard a software engineer say, “It’s not supposed to do that,” while looking at the screen of a computerized simulation going very wrong. At that moment, my mind darted back to my junior high and high school days of banging out BASIC on a Commodore PET, translating the Atari BASIC from the Creative Computing magazine, so that my friends and I could play Adventure.

You are in a deep dark cave. There is a lamp here. What do you want to do?

The microsecond burst of nostalgia closed and I knew then that if I had written the code for that software, it would be doing exactly what I told that computer to do. It took a few years to make the transition, but I let the inner geek out and consumed every computer programming book I could get my hands on. Finally I landed my first professional programming job. And have been doing that for nearly fourteen years now.

And just today, in stand up, I overheard a team member say those immortal words, “It’s not supposed to do that.” My brain seized on the phrase and compelled me to write this post before I could sleep again.

Where did your geek come from?

Be a Better Technology Manager

While browsing the deep space of Alpha Quadrant of the web this evening, I ran into a Forbes article entitled, 6 Fundamentals That Can Make You A Better Manager In 2014 by Victor Lipman. I enjoyed the brief article so much, I decided to refactor it into my own words for the manager we either want to be or want to have.

In our agile quest to improve our software and our processes, we may sometimes overlook the nuances of management. In shops with empowered agile teams, it is possible for managers to make management an afterthought, allowing the self-organizing teams to pick up the slack. It is my opinion that this false sense of security and resulting dip in the quality of management can lead to fundamental and long term organizational and cultural debt.

To avoid accumulating this management debt, team members should encourage, perhaps even require, the following from their managers. And certainly managers should strive to focus on these fundamentals even while riding on the success of an empowered, agile development team.

  1. Be open to suggestion. Seek out and embrace ideas and opportunities to improve your management practices. Be a good listener. Take regular one-on-one’s with your direct reports. Conduct “town hall” meetings with your direct reports and their teams. Encourage honest and open feedback. Don’t allow the “way it’s always been done” to overshadow your improvement courage.
  2. Expect excellence and reward it. Set high but attainable expectations. Communicate them clearly. Be gentle but firm and require regular accountability and reporting. Openly recognize and praise success. Privately discuss under-performance and obtain solid commitments to improve from under performing members of your team.
  3. Use your time effectively and efficiently. Be generous but measured with your time. Spend small amounts of planned time socializing with your team members. Be careful not to impinge on their time or waste yours. A thirty second conversation can do wonders for interpersonal rapport but a five minute chat session can degrade efficiency. Protect your schedule. Insist on well run, timely meetings. Focus on your priorities while making a top priority of maintaining a personal connection with your team. If they know you care, they will care when you need them.
  4. Communicate feedback in realtime. Your team needs regular and immediate feedback. This includes public praise for a job well done. It also includes private and direct feedback on unfulfilled expectations with an immediate call to corrective action or a resolution to an expectation that has become unreasonable. DO NOT do negative feedback by email. Back up any positive emailed feedback in person. Real words from a real person mean a thousand times more than an email.
  5. Embrace conflict. Don’t run away from or duck conflict. Hit it head on, in person, and resolve it. Don’t dwell on blame but fairly examine cause and effect and then focus on actions required to resolve the conflict and move forward. Don’t be afraid to apologize or accept responsibility for creating conflicting expectations or misunderstandings. Invite others to suggest ways to improve. Listen and see step #1.

Now go be a better manager. And if you want a better manager, share this or the Forbes article with her or him.

Insertion Sort and Sorted Merge in C#

Update (9/6/2014) - Updated code on GitHub with performance enhancement to sorted merge algorithm.

As promised a few days ago, here’s the first installment in the algorithm series. A simple insertion sort and the previous sorted merge combine to provide you with a quick way to sort and merge multiple arrays without copying data from one array to another. You can find complete code and tests on GitHub.

Here’s the insertion sort code:

/// <summary>
/// Simple insertion sort of IList or array in place.
/// </summary>
/// <typeparam name="T">Type to be sorted.</typeparam>
/// <param name="data">IList or array to be sorted.</param>
public static void InsertionSort<T>(IList<T> data) 
   where T : IComparable
{
   if (data == null || data.Count < 2) return;
   for (int keyIndex = 1; keyIndex < data.Count; keyIndex++)
   {
      var key = data[keyIndex];
      var priorIndex = keyIndex - 1;
      while (priorIndex > -1 
         && data[priorIndex] != null 
         && data[priorIndex].CompareTo(key) > 0)
      {
         data[priorIndex + 1] = data[priorIndex];
         priorIndex -= 1;
      }
      data[priorIndex + 1] = key;
   }
}

And here’s one test example:

[TestMethod]
public void CombinedMergeSortTest()
{
   IList<MergeSortTestData> a = new List<MergeSortTestData> 
   { 
      new MergeSortTestData { Name = "Robert", Age = 43.5 },
      null,
   };
   IList<MergeSortTestData> b = new List<MergeSortTestData> 
   { 
      new MergeSortTestData { Name = "Robert", Age = 23.5 },
      null,
   };

   Sorter.InsertionSort(a);
   Sorter.InsertionSort(b);

   MergeSortTestData prev = null;
   int count = 0;
   foreach (var val in Merger.SortedMerge<MergeSortTestData>(a, b))
   {
      if (null != val) Assert.IsTrue(val.CompareTo(prev) > 0);
      prev = val;
      count++;
   }
   Assert.AreEqual(count, 4);
}


public class MergeSortTestData : IComparable
{
   public string Name { get; set; }
   public double Age { get; set; }

   public int CompareTo(object obj)
   {
      var other = obj as MergeSortTestData;
      if (null == other) return 1; //null is always less
      if (this.Name == other.Name)
      {
         return this.Age.CompareTo(other.Age);
      }
      return this.Name.CompareTo(other.Name);
   }
}

Mischief Managed-Aligning Blog with GitHub and NuGet

For about a year and a half I’ve been working on various open source projects published on GitHub and several of them have packages on NuGet. When I first set them up, I used the name “duovia” which was the name of a little S corp I use from time to time for corp-to-corp consulting projects. But the name was just causing confusion for anyone looking me up and checking out my open source projects.

So I set out to simplify things a bit all around the name “tylerjensen.” I hope This will make it easier for people to find my work and less confusing when they do.

Blog Facelift and BlogEngine.Net Upgrade

Two days ago a friend of mine pointed out that some of my posts displayed a related link to one or more pages on my blog that I had not actually authored. I don’t generally use the pages feature of BlogEngine.Net, so you can imagine my surprise to find that my blog had been hacked by someone trying to promote a cause. If any of you were offended by that content, I sincerely apologize.

I quickly removed the rogue pages and found that the most likely point of entrance was a vulnerability in the combination of Disqus and the version of BlogEngine.Net that I had been running. The upgrade was not terribly hard but it was a bit tricky. Several side effects of the upgrade included a number of broken links to older posts that used double escaped characters in their title and links. This required enabling requestFiltering with allowDoubleEscaping="true" in the web.config.

The upgrade also sports a far better theme structure and rather than take the time to migrate my custom theme, I decided to go with the existing standard theme with just one or two modifications. This includes the new blog logo, an homage to the company that made my first computer—Commodore.

And finally, of course, just to be sure it wasn’t a simple case of Javascript injection via a malicious comment, I changed all my passwords. I also deleted older non-Disqus comments and updated my Disqus settings and password. For now, I’ll keep the current theme. It suits me. And with all of that out of the way, I can get back to keeping this blog current with what I hope will be useful material.

ASP.NET vNext Update from Hanselman

I’ve started to watch with eager interest the work being done on ASP.NET vNext. Read this excellent status rollup from Scott Hanselman.

Here are my favorite items:

  • Runs on Windows, Mac, and Linux.
  • Runtime in-memory compilation with Roslyn compiler.
  • Cloud optimized CoreCLR installed locally (optional).
  • New project.json system--takes NuGet to infinity and beyond.

I don’t often parrot other blog posts, but you really need to read Hanselman. If you haven’t been paying attention to what the team is doing with ASP.NET, you can repent now and get on board.

Also check out David Fowler’s blog and the official team blog.