Thoughts in the Wilderness

I decided a few weeks ago that the Wikipedia entry for Software Architect was awful. In the spirit of the Wiki, I rewrote the article.

So…now I can say that although I did not write the book on being a Software Architect, I did write the Wikipedia article

Of course, the article has already evolved through the contributions of others. So I was only the “sole author” for a day or so.

I found myself yesterday upgrading a set of Visual Studio solutions from VS 2003 to 2005 (actually, .NET 1.1 to 2.0). Now this is a fairly simple procedure, unless you want to maintain the link between the 2 versions in Source Control. This post documents my procedure for doing that, so that others can benefit.

If you are branching, you may as well take the time to correct past “structural” mistakes. In my case, my previous structure was to have all of the solution files in a common folder, and all of the projects in subfolders. This is a very flat, simple system, but it made it hard to:

1. Discover which solution a particular project was in (100+ projects, 20+ solutions)
2. Use CruiseControl.NET to monitor for changes (have to monitor each project individually)

So, my new structure is to have the solution file in a folder all by itself (give each solution its own folder), and then have the constituent projects in sub-folders. This fixes both drawbacks of the previous structure.

My source control system at work is Perforce (P4). In P4, you can define “branchspecs”, which are descriptions of ways in which you want to branch code. They are effectively mappings between target and destination files/folders. Once you have a branchspec describing the relationship between 2 branches, then future integrations (merges) become simple. So, step 1 was to create a branchspec, which maps the old structure to the new. Once that was created, I used the branchspec to create the branch.

Step 2 was to check out the branched files. (In P4, branching does not check-out the file automatically). I do this so as to allow VS.NET full access to the files even if source-control integration is broken.

Step 3 was to open the solution in VS 2005. The wizard is fairly simple and easy to follow. Don’t bother making a backup copy, because we are already working off of a copy. If you have missing files, don’t panic! Just revert (undo checkout) the branch, fixup the branchspec, and start again.

Now depending on environment, you may have lost source control integration in VS 2005. To fix: Go to File/Source Control/Change Source control. Multi-select all projects and click “Bind”, then “Ok”. There are usually some warnings with options after that; just choose the default options.

At this point you should have a working solution. If not, the probable cause is “reference paths”. You will need to go to the references for each project, and assign a valid reference path.

Finally, use VS.NET to check-in all changes. If, after checking in, you still have some files checked out, then one of 2 things has happened:

• A programmer removed the file from a project, but did not remove it from source control
• The file may be a dependency that was never added to the project.

In most cases, you can just revert (undo checkout) the files. If you find you need them later, you can always use the branchspec to integrate them.

Today I came up with a short definition of a software architect that I think is broadly applicable (to myself and others that perform the role).

“The role of a Software Architect is to recognize the edges of systems, communicate them, and define their APIs.”

“recognize the edges” – By edges, I mean both vertical (more conventionally called layers) and horizontally (separate applications). The edges are not always easy to recognize. Lots of time there is some overlap in system functionality, and the role of the architect is to recognize those overlaps and envision the possibilities of resolving them. Sometimes this means inventing new systems to fulfill more specialized roles, and then retrofit existing systems to use the new specialized systems. Sometimes it means nothing other than putting procedures in place to limit the impact of the duplication.

“communicate them” – The edges are where the politics and the business of architecture reside. A good architect can help an organization discover more efficient ways of doing business, but they will have to communicate to make it happen. And that is at it should be – the architect is the technical expert, but the business people know the business, and change is only worthwhile if it has business value.

“Define their APIs”. Good APIs are always designed. They never evolve by themselves. I know this because I have created some of my own, and I have listened to presentations from the people that designed the APIs for Java and .NET (probably the 2 biggest APIs around). Characteristics of a good API are:

• Easy to learn and use, even without documentation (discoverable)
• Hard to misuse
• Sufficiently powerful to satisfy requirements (but not much more)
• Easy to extend
• Appropriate to audience

The APIs within a system are low-level design. They are important to the maintainability of the system, but they can evolve by themselves, using techniques such as Test-Driven Design (TDD). Their audience is small and specialized. The architect has little business dictating this level of design, although they should certainly dictate which external APIs the developers will be making use of.

The APIs on the edges of a system are at a higher level. TDD (and use of design patterns) makes for bad “system” APIs, because they are not discoverable or appropriate to their audience. To use such an API, you typically need to create a few classes (maybe Strategies), or even implement an interface, and only then can you call a method which will do what you want. This is where the architect needs to step in and (writing code if necessary) ensure that the system can expose itself to the outside world in a proper way. There is clear business value in API design at this level.