Kategorie: Software Architecture

Why and How to Document your Software Architecture

Coding the Architecture provides a very nice slide set giving a very good high level overview of why and how to document your software architecture in a practical way. As I wrote, it is a slide set and therefore only provides very short summaries on the different aspects. Nevertheless, it provides some good suggestions which topics should be covered and how to document them.

Key takeaways:

  • Software architecture documentation should be complementary to the code and describe what the code itself doesn’t. For example, it’s really hard to identify things like architectural principles, operational aspects and how security works from just the code itself.
  • Keep it short and useful
  • What it should contain:
    • Explanation of the software structure
    • The architectural principles and constraints
    • Development and deployment technologies and platforms
    • A justification of how the architecture satisfies the requirements

You can find the slide set here.

BTW: Coding the Architecture contains a lot of useful resources for software architects.

97 Things Every Software Architect Should Know

In this truly unique technical book, today’s leading software architects present valuable principles on key development issues that go way beyond technology. More than four dozen architects — including Neal Ford, Michael Nygard, and Bill de h ra — offer advice for communicating with stakeholders, eliminating complexity, empowering developers, and many more practical lessons they’ve learned from years of experience. Among the 97 principles in this book, you’ll find useful advice such as:

  • Don’t Put Your Resume Ahead of the Requirements (Nitin Borwankar)
  • Chances Are, Your Biggest Problem Isn’t Technical (Mark Ramm)
  • Communication Is King; Clarity and Leadership, Its Humble Servants (Mark Richards)
  • Simplicity Before Generality, Use Before Reuse (Kevlin Henney)
  • For the End User, the Interface Is the System (Vinayak Hegde)
  • It’s Never Too Early to Think About Performance (Rebecca Parsons)

To be successful as a software architect, you need to master both business and technology. This book tells you what top software architects think is important and how they approach a project.

You can find the 97 things for free here.

Links for Software Architects

Over the time, I have collected some links to websites and articles with topics interesting for Software Architects. Since they might be of interest for others, too, I am providing them here for you. If you also have some links which you think are interesting for other Software Architects, please let me know.

Links for Software Architects weiterlesen

Dependency Injection using Unity

A nice high-level overview of  the technique of Dependency Injection using Microsofts Unity framework can be found in the May release of the MSDN magazine.

These principles include maintaining separation of concerns, using abstraction to implement loose coupling between layers and components, implementing service location capabilities, and managing crosscutting concerns such as logging and security. While these may seem to be desirable but unrelated aims, one technique can help you to apply several design principles easily. The Dependency Inversion principle implies separation of concerns through abstractions rather than concrete implementations. In terms of design patterns, you can achieve this by applying the Inversion of Control (IoC) pattern and its related pattern, Dependency Injection (DI).

The theory is simple enough. Instead of specifying at design time the actual concrete type that each class or component will use to perform some activity or process, you arrange for these classes or components to retrieve the appropriate object from a container that you previously configured with type maps and registered types.

Dependency Injection is great for achieving loose coupling of components. There are a lot of tools available that can be used for injecting dependencies. A list of such tools can be found on the Wikipedia page as well as on the Clean Code Developer Tools page.

Orthogonality and the DRY Principle

A helicopter has four main controls: foot pedals, collective pitch lever, cyclic, and throttle. The foot pedals control the tail rotor. With the foot pedals you can counteract the torque of the main blade and, basically, point the nose where you want the helicopter to go. The collective pitch lever, which you hold in your left hand, controls the pitch on the rotor blades. This lets you control the amount of lift the blades generate. The cyclic, which you hold in your right hand, can tip one section of the blade. Move the cyclic, and the helicopter moves in the corresponding direction. The throttle sits at the end of the pitch lever.

It sounds fairly simple. You can use the pedals to point the helicopter where you want it to go. You can use the collective to move up and down. Unfortunately, though, because of the aerodynamics and gyroscopic effects of the blades, all these controls are related. So one small change, such as lowering the collective, causes the helicopter to dip and turn to one side. You have to counteract every change you make with corresponding opposing forces on the other controls. However, by doing that, you introduce more changes to the original control. So you’re constantly dancing on all the controls to keep the helicopter stable.

That’s kind of similar to code. We’ve all worked on systems where you make one small change over here, and another problem pops out over there. So you go over there and fix it, but two more problems pop out somewhere else. You constantly push them back—like that Whack-a-Mole game—and you just never finish. If the system is not orthogonal, if the pieces interact with each other more than necessary, then you’ll always get that kind of distributed bug fixing.

via Orthogonality and the DRY Principle.