24 January 2015

Applying the Bosnian Model to the European Union

Bosnia and Herzegovina is a broken country. No questions about it. It was broken by the fall of Yugoslavia, but bearing the brunt of the Yugoslav wars and now by the separation into national entities. Its a place where latent conflict still lurks and which hangs together by a thin thread of heavy bureaucracy and legislature which is so prevalent in many lives of BIH citizens.

But there a silver lining. Bosnia is a micro representation of the European Union as a whole, a real life testing bed for European ideas and models. The EU has long and bloody history of conflicts,ethnic cleansing and old grudges popping up after five minutes of talking to a national of another EU country.

With so many languages and cultures living in the same place going about and handling business across the EU its not that easy. Especially the language issue. Lets face it , English is the lingua franca of the world and if you want to hop about the EU the only language you really need is English. It helps to know the local language but how can you expect a single person to be fluid in all the twenty something national languages of the union?

In Bosnia there are three main languages :

  • Croatian
  • Serbian
  • Bosnian
with a small caveat that those three languages are virtually identical. If you are a speaker of any of those three languages you can go and communicate with speakers of the other two languages without much issues. The grammar is mostly the same and the vocabulary is virtually 80% identical. But if I was required to write and speak perfect Serbian or Bosnian I wouldn't be able to. 

The solution is multilingualism. All three languages are equally official.In practice you can get official papers and fill official forms using any script (Cyrillic or Latin) and language of choice. The only caveat being that you need to stick to your chosen form.

On the EU level its a nightmare to work with the local government of the country who's language you don't know. In general you have to provide translations for everything. Its costs money, and its time consuming.

The solution for the Union would be to supplement the local language with English as the official one. You can seamlessly fill forms, sign documents and communicate with either the official local languages or using English.

As Europeans we all still to national oriented, we keep our cultures close and take it to personally anything that could endanger our perceived cultural values. But in order for the union to work we need to transcend our cultural boundaries, egos and national values and be programmatic about how the union works. Our system needs to enable the seamless protocol of ideas, people and business without introducing to much administrative, legislative and procedural overhead. Its bloody difficult just by it self to work on such a scale. We really don't need to make it more difficult.

11 January 2015

The layered architecture is broken

In the begging there was the command line , and before that the punching card, and before that we wired steam, brass, copper and electricity into simple calculating machines. Finally we wanted images to move and interact with us so the word brought us the Graphical user interface and we rejoiced in the ability to click, touch, rotate and drag things on our screens.

The systems we brought into the world talked with the operating system using POSIX commands, with each other by sending messages over pipes, tcp channels and finally using the HTTP as the universal communication layer.

The world of modern application development is a world shaped by two opposing communication forces:

  • our systems need to talk and have a meaningful relationship with humans
  • our systems need to talk and have a meaningful relationship with each other.
What lays in the between is the void we call our software, our business layer, our domains. Our work.

Why do spend so much time talking, writing, ranting, discussing, arguing about everything elese except how to best to build our main deliverable, the core of our application systems?

The reason is simple. Communication is hard. Communication is the biggest problem we humans have not yet successfully solved. 

As human beings we are tough the basics of communication, the rules governing our interactions, the principles of speaking and writing and scant else. We are left to our divise to learn the best way to communicate with each other in a variety of different context.

Software is built to simplify human systems. To facilitate interactions, processes and in the end to ease the way we interact with each other.

A modern application is not longer a calculating, mathematical system. Its a living, breathing communication entity which needs to properly interact with humans and other digital systems. It needs to be able to talk, to understand and communicate.

How we built our systems is all centered how those systems need to communicate with all other interested parties. The main architectural and development styles are all centered how to most effectively connect our main working deliverable , our logical part, with the outside world.

Nowadays its more easier to find content related how to build UI systems, application services  or persistent storage communication than to find content related how to build the core of our system. 

We all know to how develop and how to solve problems. 

We do not know the perfect way to communicate.

As an industry we are always trying to change the state of the art of  how we develop our software. In the mid twothousands we tried to escape spaghetti code applications where the application logic, external communication points (e.g. what our applications are exposing to the outside - UI, web services etc) and our internal communication points (database, web services we consume or other stuff our logical part needs to work perfectly) and thus we focused on the layer application architecture, the MVC design pattern.

A typical application architecture from the beginning of the millennium looked like this:


I present you the archetype layered application architecture. Our presentation layer communicated with our logical/domain layer who in turn used the Data access layer. On the sides we had our framework and other cross cutting aspects which pervasively transcended our layers.

It was a good model and a good starting point for all our applications then and nowadays. The problem was that it didn't work for all the scenarios we tried to do and in the end it was broken since we couldn't use this architecture to solve our problems. Thus the architecture of our solutions started to dilute, to be broken because it was really hard to stick to this process. We knew it didn't make sense for what we tried to do. 

Alistair Cockburn came with the  Hexagonal architectural model (or the "Ports and adapters") to better describe the architecture best suited for modern application (systems) development. The general idea is more aligned with hour our system ended out to be when have broken out of the layered application design. 



In the hexagonal architectural model a single solution is composed of the following component types:
  • One pure logical model
  • One or more external communication points (ports)
  • Zero or more internal communication point (ports)
  • One or more integration environments providing adapters for one or more external communication points and all internal communication points
The pure logical model is the working deliverable our system produces. It has the minimal amount (ideally zero) direct outside system dependencies needed in order to properly function. 

External communication points (ports) are the interfaces, the services, the information offering it provided to the world at large. In order to interact with the pure logical model one must go trough them. A pure logical model needs at least one external communication point, but it should provide more points grouped into different context based on the type of interaction and specif usage requirements of the outside components making use of the pure logical model.

Since external communication points are bundled with the logical model they are allowed to call and make use of each other , or better yet make use of a shared internal external communication point generalizing common outside communication patterns.

Internal communication points (ports) are required by the pure logical model in order for it to successfully complete its work. They are not required, it is possible that the pure logical model does not require services provided by other logical models, third party systems or persistent storage points. 

Internal communication points can called only from the logical model or by each other.

The combination of a pure logical model, its external and internal communication points is the first unit of reusability - a self contained unit.

In order to complete our system we need an integration environment. The integration environment is responsible for taking one or more self contained units and :
  • exposing one or more external points (ports) to different clients trough its adapters
  • providing adapters  for all internal communication points.
A single self contained unit can be exposed trough different integration points, the specifics of each integration point are not longer a core architectural choice but a plugin, something which can be changed and replaced. Thus the core deliverable of a hexagonal architecture is a specific integration enviroment serving a specific scenario or case.

The critical challenge related to the architecture of hexagonal solutions is the choice of integration patterns. And that is something we have been doing with our applications for quite some time. By applying the same principles used to build layered applications we can quite easily and more naturally build haxagonl solutions.

A specific technical example for a natural hexagonal architectural solutions is the Node.js Express web framework. Express is a very simplistic solution. In essence it provides only two things:
  • Routing http requests
  • Ability to work with Http Request and Responses on a high level
everything else is handled by introducing components called middleware, which include everything from error utilities, json serializes and deserializes, logging and our application code. 




06 January 2015

Measuring estimates in uncertain environments - another view on agile methods

I've spent the majority of my career working in the outsourcing business. Outsourcing its an exciting domain if you love technology, learning and are an adrenaline junky. Luckily I'm all three, so I fit right at home.
Outsourcing is all about making the biggest return of investment (oh, well no big surprise there) by reducing as much the development time possible in order to satisfy all the key client requirements.
When approaching any outsourcing project you have the following guarantees:

  • You are never going to know everything you need to build the project
  • Some of the technology involved will be unfamiliar to you
  • You are not going to have enough time.
In order to succeed in outsourcing you need to have the following three characteristic:
  • A self measuring and self correcting software development process
  • Strong requirement gathering and managing skills
  • Will to learn outside of regular working hours
I like to call outsourcing projects , "The big unknowns" or "Chocolate boxes" (like you never know what you are going to get). As you may fathom, knowing how much its going to take to complete a project is something of a critical information. 




In the classical, bad example model, the evil overlord of the project pressurizes the team to give the shortest estimate on the delivery which is then turned into a strong commitment. 

Notice that I'm talking about pressure here. Mark Horseman from Manger Tools talks about three different powers in an organization:
  • Role power
  • Technical power
  • Relationship power
the pressure in the above sentence is related to the abuse of the Role power, e.g, the might which lies on you by virtue of the job you are doing and its bestowed and enforced by the organization. The principal issue with the use of role power in any engineering organization is that you are dealing with intelligent, educated people working on a project which requires constant high order mental exercises day in , day out. 

You generally can't treat software engineers like they are factory workers, or farm workers where their outputs can be reasonably measured and compared and standard benchmark of operations is actually derived the lower level ability to execute a set of manual operations repeatedly. 

On the other hand you really can't let the cats fly out and what may come will come which is also the donwside of working with smart, intelligent and educated people. They tend to stray, a lot if left alone to much. 

Here we are talking about a case where estimates are forced on a team that has a low certainty level of actually delivering on them. In practice I've seen several different outcomes of this behavior:
  • Lots of overtime
  • Lots of technical dept
  • Lower quality of the delivered solution
  • Lower maintainability of the code
to give a summary we have tears and pain to spread around. Yes, yes, we all know that and we all have lived trough those moments.

And here come the agile model. The promise of freedom. Of actually delivering software that works where estimates are estimates which are actually handled properly where we are not committing to a whole bunch of work and doing a whole bunch of things at once without heads or tail where we talk to our customers who are actually part of our teams. Hurray.

By now we are all agillists and we all work in agile environments. We all know SCRUM, extreme programming and the Kaizen of Kanban. A burndown chart is not a wierd excel graph type but a living and breathing artistic expression of our ability to draw on a white board. 

From all agile practices I would presume to point one which I find most valuable (yes I know agile practices can not be taken alone, they must be bunched together, but bear with me), the built in control, measurement and correction mechanism provided by standups, sprint scrums, retrospectives and other "lets huddle around and see where we are at moments".



Lets call all those practices with the same name, lets say - PING. A "Ping" is a regular query to gather measurements about the status of the project. The only difference between each Ping implementation is the time and work scope each ping covers. Daily standups cover well one day of work so their scope is smaller, while sprints and retrospectives each cover a bigger time period.

So why is pinging so great? The greatest benefit of pings is the ability to gather real, actionable data about the status of the project without introducing any pollution in the data set. We are actually measuring what is. And when we have done a couple of such measurements we can derive the current speed of the project. And when we change something in our project or development process we can measure how much the speed of delivery is going to be affected by collecting data from our pings.

I always picture a software project like an organic machine, with gooey parts sticking and intricating them selves. The machine moves but with all the gooey parts you actually can't now at the beginning until it started moving what its speed is going to be. So you start it and it goes slow. You change something and then move it again with periodical check ups to see how its going, 

With this analogy I generally think the best approach is to pick a time frame (short one) a chunk of work and start the project. Until we have gone trough a couple of weeks with regular measurements we are not going to be able to effectively gauge the speed of the project and thus correctly estimate its length and our delivery capability.

Nothing new here, its just the old agile promise everybody is talking about. For me agile its not continues integration or test driven development, planning poker or user stories with neatly arranged burndown charts.

Agile in its essence is the acceptance of the intrinsic chaos and fallibility that is software development where each development effort is generally compromised by wild guesses, blind luck and leap of faiths. Agile accepts the chaos that is our industry, and instead of trying to change it, to mold it into well ordered bits it rids the wave and leverages its strength to deliver value to our customers instead of mounds of stinking shame. 

In my experience the best mechanism to gather an measure the speed of team is to regularly monitor it by just querying the regular status without expressing judgement or implying pressure. The results are always going to be 


01 January 2015

Microservices architecture models - How to document and think about microservices based architecture models

Today on the First of January 2015, a special day, with a special name , eleven days before my thirty fourth birthday I watched several conference presentations about Micro-services. One by Adrian Cockcroft and the other by Martin Fowler.

For those who don't yet know Adrian Cockcroft is the chief cloud architect for Netflix, a company that revolutionized cloud architecture and in a cause reaction way started up the DevOps movement. Yep, one thing they don't tell you is that when you transition to an architecture based on visualization, stateliness, and computerization of business features you drive up your costs related to the management and development of tools related to your day to day operations. It really puts Dev into Ops. Gone are the days where you could just put and app in production and forget about it on a day to day basis. Nowadays you need twenty something tools just to run and manage everything.

Well, heck, that's not what I wanted to write about today. As you may have seen I've upped up my software engineering writing and profile these days. I've writing about other stuff lately (mainly on this blog Fighting fitness , with my fiancee, about my wonderful journey into self defense and losing weight) .

The first of January started with a well made plan to work on an project I started a couple of weeks ago. Yeah, I didn't. In exchange I've spent the morning trying to find a formal definition of the architecture model Cockcroft presented in his talk at Dockercon.

I couldn't find it, but instead I found a bunch of articles and resources about the current state of micro-services architectures in the wild.

I've been involved in a government project for the last year or so, changing and modernizing a national VAT system IT infrastructure. As part of the this project we build a service oriented (micro-service based) infrastructure with the goal to reduce the load on the main VAT system and ease the development of supportive business functions (e.g. bounded context) like a separate VAT Portal for Taxpayers or a system for VAT refunds for foreign companies. And we all did that with a fairly conservative .NET stack (its the tax authority, we live conservatively).

During his presentation Cockcroft has shown several architectural graphs of the current Netflix architecture. The looked like nineteen seventy fractals from a weed high math graduate from Berkley, all accompanied by a comment that it is impossible to show an architectural model for Micro-service based architectures.

Micro-services based architecture can generally be tough as :

  • Application topology (fractals baby, fractals)
  • Data processing and transformation system (Event driven, space and time unbounded ETL)
  • Application architecture
and yeah if we are talking about the network topology we have software that can discover where, what and why we have something on our network and draw a pretty picture for us to impress everybody else but for all intent and purposes its completely useless. 

But software architecture is not about that. Its about the overreaching model of the system, the pattern we use to think and build our stuff. 

When we are designing a standard application we are never doing detailed class designs. Almost never, we do it only for the most critical parts. Instead we layout the building blocks and discuss how are they going to interact and what patterns are we going to use. 

So, why should micro-services architecture be different. Cockcroft presented a modeling framework how to describe an micro-services architecture in really simple terms. 


On bottom, the deep blue see we have our development. The basic languages (.NET, ASP.NET MVC) and application containers (IIS, Apache Tomcat, Glassfish) we are using to build our stuff. 

Next to it we have the Operations what is our main deployment infrastructure (virtualized servers in our local data center, could services like Amazon, Google App Engine or Microsoft Azure) on top of which we are actually deploying our products.

The Datastore is an interesting thing. Which database technologies we are using and their order of importance (e.g. SQL Server as our main bounded context databases, while we are using SQL Lite for less important we don't care if we delete storage). 

On top we have our micro-services element, the dev and the ops of DevOps:
  • Tooling (basic development and deployment tools - think unit testing, packaging, integration)
  • Configuration (with lots of servers, databases, services we need lots and lots of configurations)
  • Discovery (with things popping up and dieing all around us in a really chaotic fashion we need to figure out how to discover things)
  • Routing (back to the chaos of microservices, we really don't want to hardcoded every url and resource - think load balancing)
  • Observability (we need to monitor and log what the hack is going with our process , logs and events and process tracing).
Does this model help us build such an architecture. No. But it helps us see which technologies and areas we need to think about, what we have chosen and how to connect everything with everything else. 

We IT people. We developers. We administrators. We engineers, UX experts, Scrum masters and evangelistwe really like our Koolaids. We drink them mouth full and enjoy the bitter test disillusion 

The promise of micro-services is the promises of using a different technology for different projects, freedom from repressive and outdated technology stacks, a better and brighter future of easy to understand code. 

Right. 

Microservices as an architecture pattern are good for somethings. But they are not silver bullet, and with the ability to use a different technology stack for different projects is well and good should we really do it. 

In the end we are going to need people who are going to maintain all of that, and if we don't have specialist for that specific technology we need either to retrain people or build something from scratch. 

I'm a cross platform guy. I'm fluent in .NET, Java, PHP and Python. I've developed software in all those platforms and then some others to my chagrin. But not all people are really happy to learn something new and adapt to a new platform. Most stick to one thing only and live and breathe something they do not need to spend my time to learn about. They can go about their business and develop software with the ye olde technology. 


The modeling diagram above is a sketch of a process oriented architectural framework to for building reactive and scalable systems based on micro-services in .NET (with other technologies as needed). Its generally an intellectual exercise based on the architectures of the systems I've built and designed in the past (and currently working on) and somethings I've been thinking about and reading about.

On the left we start with the users. Living, breathing, stinking, eating, thinking, fidgeting human beings. The human animal with all its drawbacks and none of the benefits of a pure machine system (we miss you so much Skynet).

Our users want to buy stuff, like stuff, talk about stuff and look for suitable life companions. And they use and app or go to a web site have something installed on their machine. Lets say we are fairly conservative and have an application. 

That application has many, many distinctive submodules which all need to be presented to our users in a very unified manner. But we don't wan to develop, ship and version them together since they are fairly independent. Once a user logs in each UI application is fairly separate from the rest. They can also have different scalability request (one is used more than the other).

So we build them as separate applications, with their own infrastructure and deploy and manage separately. In front of that entire farfallini collection is the Application Context Routing App. Its only goal is to provide a single entry point for everything, a basic context and session discovery mechanism and to route requests (and their state) to specific application contexts and return specific responses from each separate business function application.

On the right most section of the system we have our micro-services silos. Out business domain bounded context. Each micro-service deals with specific business area. In general are not talking about on or two services, but a slew of services specializing for a specific context (Users, Accounting etc).

They each have their own data store and may be either called by Business function Applications or other Microservices.

How do we connect all of them? In the most simplest of terms we use the following two technologies:
  • Message queue (for eventing)
  • Web API Gateway - for routing micro service calls (and serve as a circuit breaker in case of service failure).
The general idea is that we want our system to be automated as much as possible, self discoverable and self healing and as much de coupled as possible.

In order to achieve that our services will:
  • Raise "I'm here events" or "I'm dieing Jim" events trought the event system which will be read by the Web API gateway which will in turn manage the service registry (who is where)
  • The web api gateway will queue service calls in case of failures (for important operations) so when our services fail we have a log of all calls made to them and we can execute them as soon as the failing service is up again (e.g. circuit breaker)
  • Services need to handle data stored in other services (e.g. have their own local copies) so they need to publish their internal events and react to events published by other microservices.
Does anyone think we are back into the layers end. 

  1. Web UI (Web aps instead of Controllers)
  2. Domain (Microservices instead of Business logic layer)
  3. Web api Gatweay, Message Queues and routers as the glue that holds everything together
Its all the same pasta, from the lower layers of computer interactions to our brave new world of microservices and cloud computing. 

When building microservices based architectures in the .NET world we need to really reduce the amount of time and configuration we need to do in order to build such a project. NuGET is all well but setting up a ASP.NET MVC Web API project, loading all dependencies, handle all Web.Conf configurations, create all the infrastructure classes we need is really bother.

Luckily our heroes from the Visual Studio and ALM teams come to our rescue. First of all we are not going to rewrite everything from scratch. We need to standardize whenever is possible, but make that standardization optional (we can ignore it when we need it) - call this convention over coding. We are creating a convetion of how we built things.

So if we have a fairly standard way of building our microservices why not create a set of core libraries we are going to load to ease our development effort. I call them Definitions. Definitions of terms and interactions. 



Each microservice is going to have:
  • Entites and other domain goodies
  • A way to publish services and connect to other services (we really do not need twenty way to access or read data from an internal web service)
  • A way to publish and to react to events
  • A way to interact with the Web API gateway
  • A way to access the database (or database groups).
Great, we write those libraries and publish them into a local NuGet Package repository. Next we build a sample Microservice project that works. A hello world project, or event project groups. 

And with the greatness that is Visual Studio we create project and item templates. We version those into our source configuration. And whenever we need to create a new project we use such a template.

In the end if we think about service oriented architecture, or application architecture in general its all the same thing just looked from different angles and with different terms to throw around. Each type of system has its own challenges and costs.

The important thing to remember is that systems are built by people and how those poeple think and organize is going to be reflected in the system they've built (Coneways law). 



22 December 2014



As a software engineer I've worked on both brown field and green field projects. As a young engineer I thought that green field projects were the best. The freedom to experiment and do what I wanted to learn and use the technologies I needed to learn instead of the mess somebody left for me to work on.

And then I came upon a legacy brown field project. Large in scale and large in years with a rich and complex history behind it. With problems, with issues and design decisions that stuck and made life miserable for developers for years to come.

And I learned.

Oh, boy how I learned.

I would advise any young engineer to work maintenance on any large system for a year or so. The possibility for growth and learning are endless. There is no bigger learning incentive then adversity put upon your not so strong back.

On December 5th I've held a talk for the HTML5 User group in Banja Luka where I worked for a year or so. It was the second such talk. It seems they liked the first so they invited me for one more.

As a theme for the talk I played with the idea of extending the concept of brown field software development to organizations. How to develop and integrate new software into existing organizations, organizations which are not your own which at times may be adverse to you , have their own quirks and rules.

Not to bother any one, the gist of the matter is that there are three key elements, ideas, issues, topics, and agendas one must cater to when coming to work as an outside entity into an existing organization:

  • Fear
  • Communication
  • Realism
Fear is the driving force of human kind. Fear of death, the tax man , of cheating spouses and public humiliation. Fear is to life what a cone is to an ice cream ball. Its every where, its all around us and its the primary motivation for many of our actions. As a consultant coming into a new organization you must realise that many behaviors and rules are fear motivated. Fear of change, job loss, learning, fear of fear it self. 

Communication in brown field organization development is the art of finding and understanding all information exchange pathways, who and where are the key players and what is understood, what needs to be said and what needs to be kept silent. It is imperative to join the mainstream communication pathways as soon as possible. That water cooler is your friend and that bear with the guys is never just a be.

Realism is the main principle which should govern your life. We all wish things were different. But they are not and may never be. Real progressive change is painful difficult and takes continuous effort over time. And comes with small increments. Find out what is really possible and focus on that. Everything else is a shared pipe dream. Chase your dragons somewhere else. 


01 January 2014

The emotional health of a software system

 

The eternal truth to software development is its inability to produce any meaningful systems without a coordinated effort from a diverse team of individuals, lots of disparate activities ranging from design to development and quality assurance and finally with the same effort applied to the maintenance and operations of a running system. From the deployment of patches and extensions, to the cleanup and data hygiene of databases to the scaling of the system and hardware and software maintenance efforts.

As much time and effort is spent in the art of software development, often not much effort is spent during the operations phase of a software project.

A rule I’ve often observed in many many projects I’ve been part off is the linear degradation in the effort of maintaining all the scaffolding and activities which are not directly related to coding of a software project. Thus enabled entropy degrades the product and seeps into its operations lifecycle resulting in emotional and business drawbacks for both the organization and the stakeholders included in the project.

Should we accept this? Should we accept a system of development with diminishing software engineering efforts , should we accept the fallibility of people to care and work at top quartile engineering capacity?

I’ve seen that any significant software system, shop and development environment needs guardians in the form of an engineering educated project manager and a strong cadre of technical leaders which have the authority and will to enact and drive and force a strong commitment to all software engineering scaffolding practices which combat the intrinsic entropy found in all human endeavors, especially software development with its heavy intellectual burden, high abstract concepts and emotional stresses.

A common image of software developers is of introverted emotionally challenged people. Truth be told I’ve worked with quite a few of them in my time. Thus a surprising aspect of our live is the emotional toll software development takes from each of us which is directly linked to the quality of work we do and the state of the system.

Human emotions, feelings and states directly transfer to the work we do. The pain of working with  highly abstract concepts, what in truth software development is, is the primary source of all the bad decisions, all the accumulated technical depts., all unsolved problems and defects a system has.

In order to ensure a proper functioning of a system and a team special need needs to be put in and placed under constant guardianship in order to focus on emotional and mental health of the team working under such adverse, but normal conditions.

08 December 2013

Code archaeology

 

 

8446583177_d575bdac50

There is no love, no tenderness, no emotion, no trust and no God in a piece of code. You can search, you can dig and you can wail at the injustice of it all but the only thing you are going to find are mistakes, abandoned paths, and lines upon lines of code written by people who are not here and all that they have felt, experienced during the creation of the code you are reading is forever lost, forgotten, not important.

But it is important. Recently I’ve done a lot of code archaeology, reading and analyzing solutions (some which are more then seven years old) discovering how such system are built and how are they organized with the goal of identifying pieces of code which can be transferred into the new ports of those system which are going to be built.

By reading that code I’ve found a story. A story of ideas not reached, of pressures and short cuts taken, of principles and practices which were a standard of the time that code come came from but now I know them only from my books and my own early work.

I was lucky and got to talk to the people who worked on those systems, and got to ask my questions. Why such a decision was made, why this and why not that. Is this used and why not. And I got a story of humans. People working and feeling their work end expressing them selves trough code.

The end result of each code archaeology activity was a new architecture document document the found architecture, all the technical decisions and patterns found within without judgment, written just like it is.

While doing it I found the following principles helpful:

  • Do not judge
  • Identify design pattern and name them
  • Identity individual sub architectures and follow them separately
  • Sketch

Do not judge is in my opinion the most important rule, principle and state of mind while doing code archaeology. The basic principle of the activity is to see and read what is built. The design patterns, architecture and coding style may well be something which is archaic, non modern and not pretty but it may not have been like that when it was built A web from application written in Visual Basic for .NET 1.0 is a child of its times and it is not reasonable to apply todays software development criteria to such an old system. Secondly I never met a developer who when faced for the first time with a system written and developed by someone else who didn’t start cursing and wailing about the poor quality and decisions made by the previous developers.

We developers are an opionanted bunch who would rather spend days and week arguing about what about the proper placing of business classes and their proper naming rather of accepting the current situation and getting some work done. This is actually good since is brings us to question everything and to advance as a industry as a whole

But when doing code archaeology, when reading and analyzing someone else's work this attitude will block us from seeing and understanding the software we are working with and finding it inner beauty.

The most important contribution to the modern practice of software development was the definition and introduction of Design patterns as a vocabulary and definition language which transcends all languages and software types. Thus when doing software archaeology it is most important to identify patterns of code use, name them accordingly and document their use. This practice makes the activity of analyzing and communicating the results of a software code archeology that much easier.

Any non trivial software project is actually composed of many individual sub architectures which together bring the solution to bear thus as an individual developer sees his work trough the integration of a group of classes thus a software architect sees a software system as an interaction between multiple sub architectures.

Not only it makes easy to document a complex software solution, it is the only easy way to analyze it. Modern software is complex. It has multiple moving parts which interact with each other trough time and space. A human mind can fathom only a limited set of the reality it is immersed into it at any given moment of time. Thus the only logical solution to comprehensively analyze any software system is to follow to exclusion of everything else each sub architecture boundary within is self separately from every other architecture.

Then, and only then, after each sub architecture was analyzed to its full extent. The next step is to analyze the interaction between various architecture, the same as we watch the interaction of several classes.

In the end software archeology is about understanding, documenting and the future. As archaeologist catalogue, analyze and document their findings for other to use, thus a software archeologists end product is document describing her finds. The best tool at the disposal of software archaeologist is the ability to visualize graphically old the processes, integrations and logical modules of all the key ideas being documented.