Worse and Better way of writing Software Architecture

Architecture is the foundation stone of any engineering paradigm. Every body must have known this truth. I learned this truth in every semester but only realized this when I entered my professional world. It becomes very important and comes as the 20% part of project taking about 80% of development time. It is cements as well as forms base-stone of project and must not be taken lightly. It is simply a set of codes which defines entire system and upon which feature codes are written. Once stabilized, feature codes can be staked upon it as in any house building work. New developers can easily work on it without intensive imagination of their part to understand things. All this said, Architecture writing itself is however a very difficult task. It requires a highly experienced person with great passion and dedication for writing. It also requires a great deal of imagination and technical know-how. Also, a great deal of vision is necessary for it. Its the critical part of project that can define the future of system. The architect must be very careful while writing it as it defines the boundary of overall project. Especially in a team effort this becomes immensely important. Communication becomes key to success in such teams. The problem lies not just on its technical excellence but also in its readability by team as multiple people are bound to be involved in projects sometime even getting outsourced to a different team in different nation with current architect not available at all by then!

So, here are the bad ways in which you can develop software architecture. I am working in a team that faces similar challenges which forced me to reflect upon the practices that we were following. We currently have a complete re-write of architecture in a new way that tries to support same protocols that feature codes used. So, in short we are aiming at replacing the old stack of architecture code on which we had written workable feature codes by a generic architecture. I can imagine this like Linus Torvalds planning to write a complete re-write of Linux kernel code in a microkernel style replacing the existing monolithic code without changing the application software layer. So, our manager proposed this and we liked this idea as we just had beta release and were in position to make that change. Also, it gave a challenging atmosphere to backend team which is always fun. We are bunch of people involved in that task. My manager who proposed this already had written few lines of codes of it which reflected his idea. So, here starts the bad way of development. The idea discussed was very general without any concrete definition. There was no Use case or sequence diagram discussion. There was code with lengthy documentation that connected each other like in html document. I read it for whole day trying to find clue but it just went in vain. Now, comes the worse way of writing architecture. The well documented code was just set of interfaces. We couldn't understand the connection between interfaces. Which interface was expected to call which interface? I just tried to follow my intuition based on naming but still got confused. Perhaps a simple sequence diagram would have solved entire problem without lengthy documentation. Now, comes the worst part. I was expected to write complete implementation of those interfaces and support two major feature stack over it without changing feature code. The interface had long documentation of what was expected to be done at each method but in a generic way. For example, one method just had set of expected actions to be done without any concrete way. I couldn't apply my own intuition in this as I had been bound to follow each interaction as written in documentation. There may be some things that are different while implementing.

So, here is what I thought an architect must follow while writing architecture in a team. Lets start with good way. The first and foremost way of doing it is this. Suppose an architect has a vision of developing architecture in a specified way but is not completely clear. Also, he doesn't have time for writing it and relies on other resource to do so. In such case, he can just draw a diagram perhaps give a flowchart or module diagram showing interaction between expected modules that reflects his idea. In that same diagram, expected responsibilities can be explained to team. Diagrams are always easy to remember and understood than text. Once understood, team can easily if not perfectly code it into a workable solution. So, I call it a good way of writing architecture. So, lets move onto better way. In this case, an architect writes his own code first based on his idea and imagination. His code contains few classes but those that are very important ones and includes one important use-case scenario. Remember, there is no interface!! Pattern is implemented. Once written, he calls his team and explains each class in diagram clearly showing interaction between using a top level sequence or interaction diagrams that are common UML notations. He then leaves team with task of expanding architecture. The best way is similar to the better way. The team is involved in idea discussion initially itself. The architect implements the idea as before resolving the technical difficulties involved while implementation. It may include which configuration to use or even what technology to use. As before interfaces are not presented. Classes are minimal containing important ones. Standard Documentation are provided which provides example of how and what team must document while developing later. Important patterns are implemented. Anyways, the code follows what was discussed in diagram and so does documentation. So, for team the architecture code is not like arrange marriage where every thing is strange and new (You don't know if looking or looking away from bride is appropriate). Its rather like love marriage and you know your bride very well and expect to behave in specified manner. Architect acts as a guardian when handling architecture code. For few months, he is involved in working directly with team and showing them the expected way of expanding architecture. So, seems I have acted harsh against use of interface which is not the case. I am a strong supporter of interface(even in second semester while working in C++ I had only abstract class because C++ does not have interfaces). But, its use is only clear after architecture is written and when we have different implementation. When module interaction are fixed and responsibilities of each module are crystal clear only then interfaces must come. They help in expanding architecture without changing existing codes. It does not helps while building architecture so I have supported against its use at starting phase. While expanding, interfaces are much better than simple extend. Sub-classing makes understanding code very hard.

To summarize, An architect must be involved in writing initial architecture. An initial architecture must constitute one important use case using technology and pattern that will form basis of entire system. It means while expanding, there should not be big change in technology or pattern unless necessary. Use of interface has to be avoided during start of architecture building. Once initial architecture is complete and tested for its workability only then interfaces must be introduced one by one to help expanding it.