How to write a software architecture description

Here's a great site I came across that concisely guides through the process.

http://www.codingthearchitecture.com/pages/book/software-architecture-document-guidelines.html

It looks like it based on Software Systems Architecture: Working with Stakeholders Using Viewpoints and Perspectives by Nick Rozanski and Eoin Woods.

Justifying Unit Testing & TDD

The cost benefits of Unit Testing is a interesting topic to discuss. Anyone who has experience with it or knowledge of it at least, can easily see over time it will reduce costs and increase quality. However selling it to business people always seems difficult. I often liken it to working in a factory, imagine an senior engineer informs management that with a little investment he has an idea that will significantly reduce costs, time-lines and increase quality. He can't exactly quantify, but has seen it work when he worked for a competitor. Most business people I have worked with, always want a dollar figure or a number of hours saved per year. This is almost impossible to estimate with any accuracy, and you get held to it if things look like they are going wrong.

IEEE did a study about the cost of defects at each phase of the software development lifecycle, attaching the graph they published (CostofCorrectingDefects). An online version is available here.

Quote from a study called "Realizing quality improvement through test driven development: results and experiences of four industrial teams". The full article can be found here.

“TDD seems to be applicable in various domains and can significantly reduce the defect density of developed software without significant productivity reduction of the development team. Additionally, since an important aspect of TDD is the creation of test assets—unit, functional, and integration tests. Future releases of these products, as they continue using TDD, will also experience low defect densities due to the use of these test assets”

“Convince the development team to add new tests every time a problem is found, no matter when the problem is found. By doing so, the unit test suites improve during the development and test phases”

“Get the test team involved and knowledgeable about the TDD approach. The test team should not accept new development release if the unit tests are failing”

There's also a good chapter in Roy Osherove's book "The Art of Unit Testing" (the defacto bible on unit testing). He gives an example of a project he worked on that shows two teams developing similar features with the same sized team and similar skill levels:

Stage	Team without tests	Team with tests
Implementation (coding)	7 days	14 days
Integration	7 days	2 days
Testing and bug fixing	Testing 3 days Fixing 3 days Testing 3 days Fixing 2 days Testing 1 day Total: 12 days	Testing 3 days Fixing 1 day Testing 1 day Fixing 1 day Testing 1 day Total: 8 days
Overall release time	26 days	24 days
Bugs found in production	71	11

Here's a similar story of why unit testing helps teams who use it save time and money versus those that don't: http://pathfindersoftware.com/2009/04/unit-testing-can-you-afford-not-to.

I’d say all software development teams know that unit testing is the most effective way to find bugs. According to IEEE the cost to correct a bug in the coding stage is $977 whereas $7136 in the Testing stage. That is why unit testing which is in the coding stage is so important. For Agile developments this is even more so as the code and design is changing so fast that without unit tests the whole building can collapse and many large scale agile groups see their velocity slow down: Story.

My Type Visualiser Project

I've always like to be able to visualise software designs in diagram form. When looking at code its a constant struggle to filter out the detail and only take notice of the important stuff. Most of the time learning a new code base or refactoring code the details are not important immediately. I find just exploring the dependencies of a type and other types it consumes a good place to start understanding a class. Easier said than done.

Visualising a type and its dependencies and relationships to other types, is useful to me for two reasons:
1) Assessing what this subject type is doing, and is it well structured.
2) How difficult would it be to get the subject type under test.

Enter the Type Visualiser.

This tool is intended to target one .NET type and visualise its associations.  Different relationships are modelled as different coloured lines and arrow heads.  Line thickness indicates how often a type is consumed by the subject or how many different fields or properties use other types.  The style is loosely based on UML, but is by no means intended to strictly follow UML.

The tool targets compiled .NET libraries (and executables) and presents a list of types it can find inside the chosen library.

The tool is intended to give a strategic overview of a type and how it relates to other types, so members themselves are not shown.  Only statistics and totals are given to provide a sense of how big and complex a type is. Nearly everything has a tooltip to indicate the various symbols and lines.

I'm intending on adding a Testibility Index to indicate how "testable" a type is. The more strong relationships it has (to sealed or concrete classes as opposed to interfaces and abstracts) the higher the index. The more lines of IL code and members the higher the index.  I haven't really ironed out the details of how this feature will work yet.

If there's strong interest I might open source the project.

These diagrams help me assess how much time/effort is required to get an existing piece of code under test and refactor it as well as add new features.  Obviously the more complex the diagram the more this efforts any estimates I give.  For example, this monster class shown below is definitely a huge concern in terms of complexity and the number of strong types is "welded" to.

Clearly, this subject type is broken.

Some Resources on Patterns of Data Access with EF

Ayende's thoughts on Repository Pattern.

Prefer educating Developers rather than trying to protect (preventing) them from writing bad code.

Implementing a Repository Pattern in EF

(I'm not convinced by this article. It talks about separation from Data Access but it doesn't look unit testable to me. Check out the fields on the BLL class Repository, how would you mock/stub that?)

MSDN on Testability and EF

This definitely more interesting than the above article, but I still can see how the Intelligent Query Pattern gives much cleaner separation of concerns. Although, I'm only about 90% there. There's still a case (in my mind at least) to still allow simple linq queries direct against EF.

Walkthrough of Test Driven EF 4.0

Using Repository and Unit Of Work Patterns with EF4.0

Ayende on ORM's in general

A long read, but some complimentary points on EF and good insights into NHibernate.

An tiny lightweight alternative to EF PetaPoco (although it appears it relies on SQL strings - yuck).