Software documentation with "4+1" perspectives


Thomas Gil - ©2013

Introduction

In 1995 Philippe Kruchten published an article on software architecture spelling out 4 views, or perspectives, on software. The article is titled "Architectural Blueprints — The “4+1” View Model of Software Architecture" and published in IEEE Software 12 (6), pp. 42-50. Software production results of course from efforts and interests of a variety of stakeholders: business drivers, program managers, software developers and testers, end users and operators. Kruchten's view presents and interesting and convincing model of the way these interests are intersecting which in turn influences the lifecycle of a software product and further impacts the activities of all who have interest in it - that is - stakeholders. Kruchten's "4+1" system of perspectives has been influential at least in the minds of some software architects and principal software developers I have met in my career.

In my view the desire to document software expressed in various organizations reflects precisely the intersection of concerns of various stakeholders as envisioned in the "4+1" view of the software product. Therefore I would advocate that the documentation efforts, whether undertaken before or after the design and implementation phase, be guided by these principles.

Guide to the "4+1" Views

View Focus Elements
Logical view: How the functionality is achieved through design and implementation
  • Types, classes and the interaction between instances via method calls
  • Types and interfaces that answer the question "what", classes that answer the question "how" and snippets of application logic that answer the question "when"
  • Return from methods and "long" return from methods aka exception and their handling strategy
Software development (SDLC) view: How the software product is put together and delivered
  • Version control and branching, build and release process, dependency management, determination what is provided to other modules and what is required by a module.
  • Deliverables and their packaging
Process view: What happens when the software is running
  • What is happening in the running deployable application
  • Threads, transactions, inter-process/inter-thread communication, queues and calls
  • Inputs and outputs, data flow, answers to the main question of what business is accomplished by the activity of the application
  • Controls - what features enable operator to monitor and control the application - configs, monitoring counters, log files, specialized management interfaces (like JMX)
  • Resources - sometimes called mechanisms - files, databases, queues, data stores, other applications
Deployment view: What is required to operate the software
  • What is needed to properly operate the application, OS platform with memory and CPU and storage, scripting shell, windowing system, internet reachable via network interface,
  • What artifacts are required to install, run, suspend, stop and deinstall the application - this includes perhaps several artifacts from the build - war file and config bundle + perhaps script-based configuration of sensitive information
  • Security of a given deployment - what permissions should be granted to and withheld from executing components
  • What is needed to determine that the application is behaving properly - what is the proper monitoring
The "+1" view - scenarios: How the aspects of development and delivery of the software cooperate in the functionality required in the product
  • It reflects the assertion that a system documented within the scope of these 4 perspectives is going to satisfy the functional scenarios specified to some degree at the beginning of the development process.
  • Business reason for the application to exist and be operated

... applied to various software components

There are various software artifacts and not all of them have an equal footprint on all "4+1" perspectives. Indeed only a full-fledged application designed to be a complete end-product might be seen as fully supported by the "4+1" views. In the software development process we deal with components fulfilling partial roles. There are software libraries that can be incorporated into running applications, there are scripts that facilitate deployment or installation of a running system or installation and configuration of a supporting library. There are scripts performing upgrades. There are scripts and applications that actually monitor the behavior of running applications typically on server systems. There are components that are used to generate the proper configuration for specific environments - such as QA environments or production - and run only at build time of certain software artifacts.

A code library, for example, does not own a concrete process view, but its design should indicate in what sorts of process the code could be incorporated - for example requiring transactions or other resources to be active. A library has plenty of footprint in the logical and SDLC views, but usually zero in the deployment view. Installations and upgrade mechanisms are concerned with deployment and SDLC views. The same is true of configuration generators that might run at or after build time and setup environment specific data. An executable, an application or driver, has plenty to explain in its logical view, in the process view and deployment. usually it would be thinner about the SDLC perhaps with exception of dependencies that are fulfilled in putting the application together. An application is the unit that exhibits features and we wish for most of them to be stable with progress of versions. In the deployment view the documentation would explain monitoring - that is how to verify that the application itself is operating correctly and how it can be supported.

... applied to various software process stakeholders

Furthermore, various organizational stakeholders do not have equal interest in each of the "4+1" perspectives. Program managers and business drivers are typically focused on the scenarios "+1" view and somewhat on the SDLC view even though an understanding of the logical and process perspectives are quite often useful in learning what functional requirements can be realistically implemented. Software development managers should be concerned with both the logical view and with SDLC view and almost to the same degree with the process and deployment views. Software developers are mainly looking at the logical view but need to work with the scenarios view to implement the features asked for. Developers perform best if they are mostly isolated from the SDLC and deployment view but should be mindful of the process aspect of their work. QA engineer might skimp on understanding the logical view but should should stronger in the interest in the deployment view. Operations and infrastructure engineers would be strongly interested in the deployment and process view. A special case of the deployment view is the view of an end user who installs an application on his/her device or computer because then the setup and monitoring of the application is an end-user feature.

... and not applied to data modeling

The design of the data model is a problem of a different nature and does not fall under the scope of the "4+1" views of software. The gaol of the design of data - with the purpose of storing it in a relational database as is most often the case - is the ability to reflect accurately the instantaneous state of the world - at least the portion of it a software system or a business is concerned with. For example the data model will have an answer to the question what shipments are currently carried in the cargo of our trucks and what are the destinations on those shipments as well as what are the destinations of those trucks. This is an instantaneous view of the world (actually just our business in it). In data modeling we are concerned with this ability as a goal and it is achieved by examining the logic of entities and their relations which can then become a foundation for the logical of software applications and physical data schemas implemented by databases and other data stores.

Concluding

To summarize, the "4+1" perspective system gives a comprehensive coverage of the architecture of a software system. It allows to delegate the responsibility for portions of the system to appropriate stakeholders. During the documentation phase it assures that all the important aspects of the system are covered.