III Project🔗

What is a software system? What goes into its production?

A software system is many lines code in the same way as an ant colony is a large number of ants. Everyone knows that there is more to an ant colony than the huge number of ants. Likewise, a house is much more than a large number of bricks combined with mortar; it consists of walls and roofs and doors and many more distinct pieces. In this spirit, a software system is more than just 10,000 lines of code or 1,000,000 lines or even more. It consists of major and distinct building blocks, often called subsystems or components; and yes, deep down these components consist of code, but as we shall see, “lines” is the wrong idea even at that level.

Identifying and delineating these major pieces is the first goal of any software development project. To find the pieces, it is necessary to study the various ways how the system interacts with its context. Once the major pieces and their interactions are identified, someone can make a construction plan and assign the construction of the various pieces to teams and pairs of developers.

Getting Started, Getting Stressed

The following sections provide a detailed look at the nature of software systems and the first phase of the production process. An understanding of how software systems functions is a prerequisite to recognizing what their major pieces look like. Identifying these pieces differs from era to era and from team to team. But, at this point in time, we understand the basic steps of getting from a problem statement to a software-construction plan. Understanding the general idea of process will also help developers who join projects long after the initial product has been constructed—especially if the developing team has taken the time to create a document that explains the specifics of the system: how it came about, how to view the “big picture,” and how to navigate to the “details.” In short, A team acting in a responsible manner will greatly help on-boarding developers later.

7 Running a Software Systems🔗

How does a software system function?

Before we tackle the question of how to construct a software system, we need to look at how a system is run. Reflecting on how software systems work will help understand the analysis step, the component identification, the planning phase, and more. Clearly, an operator must launch a software; when it runs, the system will respond to requests; and eventually the operator give the system a command to shut itself down gracefully, which may include preparation for the next run. But, people have also come to expect that running software systems adapt to new contexts and end-users. That is, the system adjusts itself to various settings: it configures and re-configure itself; it loads and unloads pieces dynamically; and it cooperates with external systems if needed. Figure 3 illustrates a run with an abstract “plot sketch.” Keep it in mind as you read the remainder of this section.

Figure 3: A typical run of a software system

The Abstract View Let’s take a look at each phase of a typical software system run, while thinking some of the systems you have already used: a web browser, an IDE, or perhaps an networked game. When launched, a system configures itself according to instructions from the command-line and/or a configuration file. During this configuration process, the system loads components, components initialize themselves according to configuration parameters, and one component will pass configuration information to others.

While this setting-up process lasts, the system goes through a period of instability. Components may become available in a concurrent manner, meaning the order in which they are loaded or connected is unpredictable. Hence, any individual component cannot assume that the services of some other component are available when it starts up. Once the configuration is completed, the system transitions to steady-state processing.

In this steady state, it responds to requests from the outside. A request typically triggers the execution of some service—runs some pieces of functionality, one after another or perhaps in parallel—and in the end delivers a response. An external requests may trigger the loading or unloading of components. Such run-time extensions dynamically integrate modules or classes into the running code. Others execute components as separate processes—to isolate the main system from any effects of the subsystem—and communicate inputs and outputs via operating systems facilities (files, pipes). Yet others connect to completely external components for a time and then disconnect again.

In such a multi-component system, some services are critical and some are optional. A component is critical if a failure in the component implies that the system can’t deliver a response to an external request that the context considers absolutely necessary. A component is optional if its externally visible effects are of a low-priority nature.

Exercise 2. People have come to expect the fault-free, continuous execution of some software systems, for example, the phone network or the internet. But even these systems suffer from problems on occasion. Their reliability is thus measured in “the number of nines.” For example, “five nines” means the system is up and running 99.999% of the time, and that it may be down for less than 0.001% of the time. Calculate what these percentages means for one month and one year.

Finally, sometimes operators must take down a software system. When a software system receives the request to shut down, it must do so in an orderly manner. It should save any data it may need for a re-start. It should disconnect from external systems properly, which may mean unloading components. It should terminate any external processes that it launched. Generally speaking, it should release its resources. Modern operating systems properly manage resources, but some software systems must run on impoverished platforms. Like the start-up phase, the shut-down phase may induce some instability, and it is thus imperative that the system no longer response to requests during this phase.

A Concrete Example The above overview is quite abstract. It demands a concrete example and an illustrations of these points.

Every reader is familiar with IDEs, interactive development environments. These IDEs are software systems in the sense of the five bullets. When a typical IDE starts up, it consults its configuration file or directory, where it stores information such as language modes, recently visited files, positions within files, and much more. If the IDE is directed to open a file for which a language mode doesn’t exist yet, the services for parsing and syntax-painting the code aren’t available—but this must not prevent the IDE from starting up and asking the programmer for information on how to configure these pieces of functionality.

Once the IDE is up and running, a developer can edit the code, query it, refactor pieces, run tests, and so on. A bug in the parsing tool or language server will not tear down the IDE; instead the IDE will signal that there is a problem and ask the developer how to proceed. On the other hand, if the IDE code itself has a bug, the developer may have to “kill” the IDE process and restart it. But even in this bad scenario, the IDE won’t let down its user. It will have stored away enough backup and recovery information that the loss will be tolerable. Finally, a developer is likely to shut down an IDE in the evening and restart it in the morning.

Now that we have a common idea of what a software system is and how it runs, we can turn to the next part, namely, the construction of systems.

Exercise 3. How could an IDE become unstable while it is looking to load a language mode (parser, type checker) while a developer is creating code in this language new to the IDE? What if the IDE replaces a language mode with a revised version? Look up the term “hot swapping.”

8 Developing a Complete Software System🔗

How is a software system constructed?

A modern software system consists of many interacting pieces of software. Over time the pieces have been called by different names: component, module, package, plug-in, (micro)service, and more. These names reflect our growing understanding of the nature of software systems plus the advantages and disadvantages of these organizations.

Early on, programmers thought that these components are designed, implemented, linked, and deployed for good, like any other large engineering product, say, a bridge or an airplane. Once a product was deployed, it just needed occasional maintenance action, perhaps a bug fix or a port to a some new hardware.

Now we understand the nature of software differently. People view software as the extremely malleable medium that it is. They want bugs fixed immediately; they want new features added asap; and they don’t have time to wait for the responses of a system. All of this calls for highly responsive developer teams and instantaneous delivery. In short, software construction has become maintenance and maintenance is continuous construction. One key consequence is that developers have to look at existing code quite frequently and reconstruct the thoughts of those who constructed it.

To understand what the construction of a software system looks like, this section presents the imaginary scenario of being in charge of a brand-new project. Some call this situation a “green field” project. Although this situation is rare, it is idea for getting a sense of how the system’s purpose is refined; how its components are discovered; how these components are arranged into a whole; and how developers describe the results of this work. After that, it’s onward to programming—but all of this work is software development.

Figure 4: Software development processes: waterfall and spiral

8.1 Ways to Proceed🔗

In the early 1970s, Barry Boehm, one of the first software engineering researchers, wanted to explain the cost of bugs. More specifically, he wanted to understand the relationship between the cost and the time of bug discovery during development. To do so, he first needed a model of development, for which he borrowed a simplified model from ordinary engineering.

Figure 4 (left) shows the essence of Boehm’s process idea, the waterfall model. The engineer starts with a thorough analysis of what the software system is to accomplish, its context, its performance characteristics, and so on. The result is a document of requirements, and it is “thrown over the wall” to specification specialists. Their task is to turn the requirements document into a system specification, often called a software architecture. Once again, the architects hand this document to people who can write down concrete component specifications: interfaces that spell out which functionality is needed and purpose statements for each piece of functionality. From here, the workflow goes to coding, testing, and integration testing until the system is ready to be deployed. The rest is simply called “maintenance.”

Boehm used the diagram to state a simple-minded exponential law of bug cost. If a bug is discovered n phases after its introduction into the development process, its cost is O(10n) (time, resources, money), an amount that covers both the direct damage caused by the bug, the effort of finding the bug’s source, and the labor of eliminating it. Boehm’s paper implies that the model is a strawman, and the number is just a “guestimate.” Nevertheless people tried to follow this waterfall process of developing software, and in principle, its sheer existence is critical because it identifies important intermediate products: requirements; architecture and its components; unit tests and integration tests; deployment documentation; etc.

In 1976, when Boehm consolidated his presentations into a book, he presented a refined variant of this waterfall model of software development: a spiral version. Here “spiral” means that each phase in the workflow diagram of figure 4 (right) is equipped with a backarrow to its predecessor. These backarrows indicate critical feedback, which demands a conversation between the people working on phase n+1 and those working on phase n. In the terminology of Boehm’s book, a component specifier would conduct a thorough review of the software architecture and thus provide feedback for improvements. This conversation continues until the component specifier is satisfied with the architectural specification. In turn, a demand for revisions to the architecture may raise questions about the analysis of the purpose and context of the software system. Generally speaking, the document of phase n is no longer chiseled in stone but a negotiable product, and the negotiations may flow all the way back to the origin.

By 2000, the ideas of agile development and extreme programming changed the landscape of software development even more. Coding is no longer seen as a minor step in the middle but as the beginning-and-end. Testing is tightly integrated with, and drives, the development of code. Due to internet-based delivery of software, deployment and maintenance aren’t separate phases anymore but simply become another element of a tightly knit development-and-feedback cycle.

At first glance, the analysis of requirements and the design of an architecture plan seem to be missing, but these appearances are deceiving. Both are still needed, though they may not play the same role. Without a goal statement and an analysis of this statement, developers don’t know where they are going with their software. So formulating the goal, and analyzing how to get there, is a requirements analysis.

In the same vein, a software system without some architecture cannot exist for a long time. Like a plan for a home, a software architecture is a blue print and a guide to the numerous interacting pieces. While a process such as spiral development develops a draft architecture explicitly and up front, agile and extreme-programming processes create this understanding over the course of the creation phase. It may be implicit at first, but when the software development process is successful, someone will have to describe the architecture explicitly if the “owner” wishes to maintain the product for the long run—or suffer the consequences of a socially irresponsible development process.

Reading

Barry W. Boehm. Software engineering. IEEE Transactions on Computers. 25(12). 1976.—On occasion, it is worth our while to read original literature, especially when follow-up characterization of this work are rather murky.

Kent Beck. Extreme Programming Explained. Addison-Wesley. 1999.—In this short book, Beck argues for “programming” as the central, creative activity and explains how a “programming first” approach to software development may work in practice.

The Agile Manifesto Kent Beck, et al. Manifesto for Agile Software Development. 2001.—Beck and many other signatories published a dozen principles describing a flexible approach to software development. They fit on a laptop screen, and decades later it is an interesting read, if only to understand how this short piece affected industry at many levels.

8.2 Analysis: Understanding the Project’s Purpose and Context🔗

Although this book is not about software engineering, it is still important for a student of software development to see how an experienced developer might conduct a rudimentary analysis—because it helps explain to an on-boarding developer the state of the software. A budding developer must understand how software systems start with an idea; that they are always placed in a context; and that their operation is about interacting with this context. Once this much is understood, it is possible to create a rough, high-level sketch of the components needed to implement the desired functionality and how these components depend on each other. The goal is to put the development team into a position where it can begin to work out a construction plan.

Figure 5: A spiral analysis of an imagined software system and its context

Every project starts with an idea about some piece of functionality that people would like to have implemented as a piece of code. In the beginning, military men needed weapons-related calculations done. Engineers aimed to help with the construction and control of airplanes and space ships. Scientists wished to model the weather. Business people wanted to replace the tedious paper-based bookkeeping with accounting software. Doctors asked for assistance with diagnosing illnesses. Once the world-wide web came about, travel agents lost their jobs to web sites. Drivers ditched their city maps and used web-based navigation systems for trips around town. People also imagined how others might like to share experiences via stories, links, pictures, videos, and so on. The addition of the cell phone brought all these things and many more to our finger tips wherever we went, whenever we requested them.

This short history points to a key insight about software: it never exists in a vacuum. Software entrepreneurs and their developers must understand and keep in mind the context in which the software lives. As a matter of fact, basic development practices alone demand that they investigate this context before they even start.

Diagram 1 in figure 5 illustrates this insight. When someone wishes to build some software, it is common to have an idea that any non-trivial system (the square) will consist of a bunch of components (the black rectangles inside) and that it connects to some context, which actually determines how the software will be used. It is natural to proceed in a spiral-like fashion, outwards from the imagined software system, to explore this context.

As an analyst investigates the very first layer around the software, operators come up; see diagram 2 in figure 5. An operator could be a soldier, a construction worker, an accountant, an engineer, or just someone looking up a friend’s latest dance video. It may not even be a person, but a thermostat, a camera, a light switch, or even some other software system. Whatever it is, it must be able to stimulate the imagined software system so that it responds. This response could affect a person, or it could turn on/off a mechanical device such as a cannon, the injection part of a car engine, a phone’s speaker. Indeed, it may even be a message to some other software system. Let’s call this the stimulus-response layer.

Next an analyst is likely to find passive observers; see diagram 3 in figure 5. These context elements may perceive the existence of the software; they may experience the effects of the system; but they will not directly interact with the software. If the software malfunctions or disappears, some may notice, some may not; some might become unhappy about it; some may welcome it. Consider a software system for designing aircraft wings. The engineers at Boeing will interact with it. By contrast, the pilots know about it and may notice that their new airplane consumes less fuel than the previous model. Similarly, the guests of a restaurant may face TV screens that show some political conversation and most would likely be happy if the systems malfunctioned.

Figure 6: Drawing the boundary between a software system and its context

Finally, when the analysts have explored the context to a sufficiently large distance, they will notice that more and more unrelated concepts show up; see diagram 4 in figure 5. Think of the passengers in the airplane or the air-traffic controllers, none of whom will interact or even consider the wing-design program mentioned above. They all just don’t matter for the product development.

At this point the analysis is concluded and yields two critical pieces: a description of the relevant context and the boundary between the software and its context. Figure 6 makes this point with the triangle that separates the core functionality and its operators-and-observers context. Now is the time to study the results of the analysis so that a developer understands the uses. This step focuses on the operators and how they might interact with the system, that is, the entire path from a stimulus to a response. It also includes the observers and what they may wish (or not) to experience when the software runs. A consultant may also make a plan on how to deploy the finished system and how it will affect the people in its context.

8.3 Synthesis: Discovering Components🔗

Drawing the boundary between an imagined software system and its context is key to figuring out the system’s major components and the role they play. The starting Experienced developers know that this idea generalizes to component creation. point of this step is the set of operators in the context of the system. After identifying them, we need to determine how they stimulate the system; we need to imagine how this stimulus triggers communications among the system’s components; and we need to describe what the response is and which pieces of the context it affects. Software engineers refer to this step as a use-case analysis.

Figure 7: Understanding use cases

Figure 7 displays two diagrams that illustrate a use-case analysis. The diagram on the left shows how an operator stimulates the system. The stimulus affects one of the system’s components. In turn, stimulating this component triggers an internal event with another component. One way to understand this second step is to think of a shift of the boundary. The active component has become something like an operator, and to get its computation performed, it stimulates another component. From the perspective of a stimulus-response chain, this second stimulus is the response of the first component to the operator’s stimulus. This process continues until the software system is ready to issue a response to its context. In the case of the left diagram this response goes back to the original operator. As the diagram on the right side of figure 7 shows, the response does not have to go back to the operator; instead, it could be a signal to passive observers.

Keep in mind that operators and observers are not necessarily people. An operator could be a sensor, such as a thermometer, combined with an actuator, say, an air condition unit (A/C). A thermometer sends measurements to a software component that checks the measured temperature relative to some preset value. If the measured temperature is above the present value, the software system may request cold air from the A/C. Or, think of a smart phone. It is essentially a large software system that may receive messages from other software systems: a ping from a cell tower, an old-fashioned text messages, notifications from social media, a signal for its clock, and many more. While a ping may demand an acknowledgment from the phone, a signal to the clock should not require a response (though an owner may notice when the clock adjust to a new time zone).

The purpose of a use-case analysis is to discover a system’s essential components. A component typically represents information with data and implements a complete piece of functionality. In a smart home, the software system may come with a control component for configuring the various devices in the home. And, this control component is likely to connect with communication components (drivers), which translates operations from the occupants and sensors into actions. A communication component will interact with actuators in the home, say, music players that send the sound to the speakers in the room where people are or light switches that turn off all light bulbs when everybody has left a room.

Figure 8: From use cases to component identification

Figure 8 displays the diagrams like those in figure 7 but with an additional. Concretely the diagrams contain a gray-shaded component. The diagram on the left indicates how this component was missing from the stimulus-response path that starts at the operator icon on the right and whose response goes to this very operator. Think of a component that renders an internal data structure into a visual presentation that a person can understand; or imagine the translation of an internal piece of data into a piece of information for an actuator. The diagram on the right in figure 8 shows a use case that shares a prefix of the stimulus-response path with the one on the left. But, the newly discovered component does not become a part of this use case. Generally speaking, every use case deserves its own careful analysis.

This list of examples is by no means exhaustive, but it should help with the important idea of separation of concerns as separation of components. By keeping key pieces of functionality separate, developers provide direct help with the future maintenance. If it turns out that a central data structure is a performance bottleneck, a developer can probably change its internals without changing other parts of the system. Other kinds of changes to functionality can also be isolated to one component or two if different concerns of functionality are allocated to different components.

8.4 Planning: How the Construction Proceeds🔗

The analysis of a software system’s context develops the big picture idea. Here “big picture” means seeing the system in context—the idea, the operators, the observers, and their general relationships—as well as drilling down to discover key details, say, the exact relationship between the system and the external actors. In computer science this way of proceeding is called top-down.

Proceeding in a top-down fashion is still appropriate when developers perform a use-case analysis to discover the distinct components of the system. The big picture here consists of the essential data representations and the key pieces of functionality. The “drilling down” discovers such details as to the existence of one component may depend on the existence of (functionality in) others. Understanding the exact nature of these dependencies is not yet critical.

Figure 9: Layering the identified components

Figure 9 displays a suggestive layering diagram of some of the sample components mentioned in the preceding section. An arrow from A to B should be read as “component A depends on component B.” In this sample arrangement, the foundation comprises the central data structure component and the component that records knowledge about external actors. Layer 1 consists of two components: a component that represents the external actors and another one that implements how to communicate with them. The top layer implements the actual, physical communication, perhaps via a remote-proxy pattern.

Exercise 4. Organize the five components in figure 9 into a linear plan sequence so that a component listed at position n+1 depends only on components 1 through n.

In addition to inter-component dependencies, external constraints also play a role in the composition of a construction plan. For example, the ability to demonstrate a working prototype might dominate other concerns. Consider the development of a software system that may have to rely on interactions with external software systems. A client, a marketing person, a manager, or an investor may be happy to see a prototype that merely implements the logical communication and runs on just a single computer. Depending on the various desired features, this stage can be broken into several smaller ones, too, as long as each of them comes with observably distinct functionalities.

9 Software Architecture🔗

While developers identify the components of a software system, they also develop an idea of how these components relate to each other. Conversely, existing ways of relating components to each other tends to determine a bit how developers identify components and their relationships; on some rare occasions, developers come up with new ways of arranging components or at least variations of existing arrangements. Before we continue, it is therefore necessary to take a look at these preconceptions.

Researchers refer to these established and widely used arrangement of components as software architectures. They coined this phrase to describe an entire field of study. Practicing software architects view the use of (variants of) existing architectures as a way to arrange components so that the overall system is easily understood and effective. In other words, it is a small act of socially responsible development.

Any developer team that grows to a certain size has a dedicated architect, and many developers consider this aspect of software development a sweet spot. Becoming a software architect requires experience and reflection. The former starts with knowing some basic architectures; the latter means having an eye for proper relationships among components.

This section presents three architectures that every developer should know. There are many more, and descriptions can be found in the researchThough be careful, this very literature can lead people to turn into “architecture astronauts.”literature. The notion is also somewhat related to the field of object-oriented design patterns, though as the name says, the latter is focused on a specific class of programming languages (and how to circumnavigate some of their deficiencies).

9.1 Pipelines🔗

The Unix operating system introduced the pipe as a mechanism for composing programs that read their arguments from a standard input device and write their results to a standard output device.

Operationally, the pipe mechanism enables a programmer to turn the standard output device of one program into the input device for a second program. This way the second program can process the output of the first and compute its results from those. A pipeline is a composition of several programs with pipes between them. While the idea sounds simple, it has consistently shown surprising value and has been ported to almost all operating systems.

Figure 10: The pipeline architecture

Figure 10 displays a diagram that illustrates the idea geometrically. Each component consumes an input stream, which contains a number of elements. It also produces an output stream, again a sequence of elements. The shaded elements of the input streams are those that the component has consumed. As the diagram also shows, different components process their input streams at different speeds.

Depending on the relative speeds, one component may have to wait for its predecessor. The pipes-as-streams mechanism smoothly accommodates such differences, because it clearly distinguishes the end of the stream from the situation when the next element is not ready for processing yet.

The ls -l command—that is, a program ls with a commandline flag -l—displays the files in the current directory to the standard output device, one per line. This output device becomes the input for the following command. The grep program searches its input stream for the word given on the commandline (rkt) and displays only those lines that contain the word. Finally, wc -l counts the lines of its input stream. In short, the pipeline counts the files in some directory whose name contains the word rkt. The result of the entire pipeline is 15.

This pipeline uses cat to display I.scrbl, the source of part I of this book line by line; breaks it into words; sorts those; eliminates duplicates; and finally displays the first seven words.

9.2 Model, View, Controller🔗

The introduction of graphical user interfaces in the 1970s pointed out the essential difference between the data that a program manages, the way the data is presented to customers, and how the latter interact with this presentation. To realize this separation, a developer at Xerox Parc proposed a three-part architecture: model-view-controller.

Using standard science terminology, the model is the essence, the data set that the software system manages. A view—notice the indeterminate article—is a way of displaying the data; one data set may have many views, with none being necessarily superior to any other. If a user wishes to interact with a particular view, the software system needs a component that translates the user’s gestures into updates to the view and changes to the model—as needed.

Figure 11: The model-view-controller architecture

Figure 11 presents the idea as a diagram. An model-view-controller architecture consists of one model component and 2 * n controller and view components. The latter come in pairs, because each view may need its own way of allowing users to interact with the system. The diagram shows that the user understands the data through a view presentation and that any gestures of the end-user are related to the model via a controller for a view. In turn, the model component informs the view of changes to the data display.

The ubiquitous spreadsheet is an early and well-known system that employs the model-view-controller architecture. An end-user enters data and can then request different views of the same data with various gestures: tables, bar charts, pie charts, etc.

Similarly, many modern IDEs make use of the model-view-controller architecture. An IDE may display the full program text or an outline view; it may show a hierarchical project view; and it may allow programmers to interact with the system via a console.

9.3 Client, Server🔗

Another Xerox Parc effort—a networked or distributed file system—led to the client-server architecture, that is, the classification of some computers as providing a service and others as being clients of this service. The architecture has found many uses since.

A classical client-server arrangement consists of one server program running on a computer and an arbitrary number of client programs, usually but not always running on different computers. Each client interacts only with the server. It sends a request message to the server, asking for some data or for some work to be performed on its behalf. The server sends back a response, the requested piece of data or just an acknowledgment that the work has been performed.

Figure 12: The client-server architecture

Figure 12 shows an instance of a client-server architecture, where six different clients are simultaneously interacting with the server. Here the server sits in a “central” location, indicating that it should be easily reachable for all expected clients. The double arrows between the clients and the server—and the absence of any other arrows and liness—are the only communications that take place.

Every computer user is implicitly familiar with the client-server architecture. The web browser on laptops sends requests to a web server. Simple requests ask for the content of a file, usually with some HTML content, which the browser then renders on the user’s monitor. The response may contain JavaScript programs, which turn the browser window into an interactive graphical user interface. Complex requests demand that the server runs a script that composes the response.

Many apps on people’s mobile devices (phones, watches, cameras) play client to servers. Some are simple software wrappers around web browsers and essentially act as such. Others are genuine graphical user interfaces whose model partially resides on the mobile device and is supplemented by data on a server, which is retrieved via request-response actions.

While the classical client-server architecture typically replies with one response per request, alternative variants exist. For example, a request from a client to a server may initiate an entire conversation, consisting of many back-and-forth messages. Indeed, the server may engage with other clients at the same time, concurrently or sequentially, and the server’s responses may even depend on how other clients react.

Reading

10 A Sample Project: Analysis, Discovery, Planning🔗

Planning a Project

Imagine a brand-new startup that wants to engage “hackers.” The founders noticed that “hackers” are mostly bored on their jobs and complain about the bad habits of their teammates. So, the founders wants to run servers that host tournaments of board games, and “hackers” from all over the world will produce automated players that connect to the servers. These “hackers” will pay a small fee to have their automated players participate in tournaments, and the winning player (and its owner) will win a significant prize. The founders are also considering broadcasting the games to paying subscribers, and like in all unicorn dreams, these broadcasts could become channels for delivering advertisements—though this really is just a dream for now.

Figure 13: The player-client/game-server architecture

Starting with this description of the idea, a software developer no longer sees a blank slate but the idea of the client-server architecture in figure 13. The clients are the automated players; the server is a game server. Player-clients request to participate in the game, and the game-server arranges through its responses for the execution of a game. The architecture differs from the classical one in that (1) the server and the client exchange a series of messages—they conduct a complete game with many turns—and (2) depending on the nature of the game, the server arranges these conversations in a particular order, as indicated by the dashed arrows in the figure.

Note To simplify the analysis, discovery, and planning, let’s ignore the financial side of the software system. This side of the business is mostly orthogonal to its core functionality: running games and tournaments.

10.1 Core Idea🔗

The starting point is somewhat clear. While human players tend to manage a game jointly—agreeing to and interpreting rules together; dealing with common game tokens together or putting a trustworthy person in charge—a software variant calls for a neutral party, and that part is the company’s software.

Following tradition, let’s use referee for the component that manages a game. It will have to rely on a representation of the game pieces: the map, the colored cards, the rails, the destinations. Furthermore, it needs to represent what it knows about the participating players so that it can enforce the rules.

Beyond games, the software is also in charge of running tournaments. This task is completely separate from refereeing a game, so a tournament manager is called for.

10.2 Context Analysis🔗

The operators are “hackers” who run automated players. Where these operators exist seems to be unrelated, other than that the company’s interaction with the players must allow for long distances. If the company runs its servers in Seattle and the automated player executes on a computer in Capetown, communication between the two takes longer than the method calls between a “house player” and the game-serving software.

Concerning observers, the company must certainly accommodate its investors. Most investors do not care about the code—although they probably should—but a company can impress them with visual effects. Additionally, the human operators of the server software may wish to have some visible means of checking on the progress of individual games or entire tournaments. Finally, the “business plan” calls for subscribers to be able to watch games, possibly for a fee or in exchange of watching advertisements.

Outside this circle of operators and observers, an analyst may see sports bars, the parents of a “hacker,” server-machine farms, and many more things. In reality, though, the concepts identified so far describe the software system’s components and its context as much as needed for now. Put differently, the description clearly tells us how to proceed with the development of the core of the software system.

10.3 Component Discovery🔗

The context analysis yields a description of the system’s environment with operators and observers. Imagining these external actors, an analyst plays through key use cases and looks for the components of the clients and server in the imagined architecture of figure 13.

For Ticket to Ride, the analysis has unearthed six components: a tournament manager, a referee plus data representations for the map, the cards, the rails, and the destinations. There are two operators: “hackers” and automated players. At least two kinds of observers are essential: the people who monitor the running system and those who invest in the company before it goes unicorn.

Let’s look at how these external actors interact with the game system, keeping in mind that, like all software systems, the game server starts up, runs tournaments and games, communicates with players, informs observers, deals with failing components, and eventually shuts down.

Launch The “hackers” want to launch their automated players and connect them to the company’s server software. Just stating this much of a purpose raises two questions. The first one is what they connect to. The tournament manager is the only identified component that could even remotely play this role. But then the tournament manager would take on two distinct tasks: managing a tournament of hundreds or thousands or more automated players and signing them up. If the idea takes off, the two tasks might have to be performed concurrently: while a tournament is going on, the next wave of automated players is signing up. That is, this part of the use-case analysis points to a gap in the component identification process. The game system needs one more component, one that signs up automated players and launches tournaments via the manager.

The second question is how the automated player contacts the sign-up component. Since the automated players and the game system will run on two separate computers, choosing a physical, or remote, communication protocol is necessary. The choice will determine how a player connects and how a game server interacts with the players.

Running a Tournament Once enough players are signed up for a tournament, the manager should inform the players to get ready for their first game. Similarly, when the tournament is eventually over, the manager component should let the players know. At a minimum, the winner(s) of the tournament should find out that they won a lot of money.

What this use case immediately points out is the need for a logical communication protocol between server and player. This protocol specifies how the game server and its components contact the players, which information is revealed and as what kind of data it flows from the tournament manager to the player, and what comes back.

Note that this concern is separate from the choice of a physical communication protocol. Since logical ways of communicating is a distinct concern from the transport protocol and the shape of the message, the implementations of these two protocols should exist in separate components.

Running a Game The tournament manager will put instances of the referee component in charge of running games. Like the manager, the referee should inform the players about the start of the game and the end, at least the winners of the game. Furthermore, for the chosen game, the referee should grant players turns, in the round-robin fashion typical for board games. Once again, this use case calls for an extension of the logical communication protocol.

Communication Concerns The preceding two use cases allude to the logical ways of interaction (between the company’s software and the players) and remote communications. Both forms of interaction need rigorous testing before the company runs its first tournament. Testing the logical interactions is different from testing remote interactions; it relies on an implementation of logical players, that is, players that directly interact with the game software without going through any remote-communication protocol. This If you are unfamiliar with design patterns, check out online resources, for example for the remote proxy pattern. observation exposes another oversight in the original list of components. Performing the second kind of test demands an implementation of a bridge between the game server and the logical player; software design principles suggest looking into the remote proxy pattern.

Observing Any observer will want to watch how games progress and how the tournament progresses, two rather different forms of observation.

Watching a tournament is about observing the progress of individual players. Imagine a knock-out tournament in which only the winner(s) of a game may move to the next round. An observer could bet on the tournament rounds, just like people bet on the NCAA March madness tournament or the European Champions League play-offs.

Watching a game publicly calls for visualizing the map and the acquisitions that players make during their turns. Looking over the shoulders’ of a player should be like watching a game but should perhaps reveal the player’s private knowledge. These ideas point to yet another concern: privacy, which, to keep things simple, is ignored here.

All these cases call for different observer components and a communication protocol that sends information from the manager and the referees to the respective observers. The observer components differ from each other, because the visualization and the intended audience differ. Just as with operator interactions, the server-observer communication protocol calls for two layers: a logical layer and a remote layer, if the company wishes to enable observers at distant locations.

Failure All remote interactions between a system and its external agents may fail. Furthermore, all logical interactions may fail due to a bug. Neither kind of failure should bring down the entire system, unless the failure is in a critical component, say, the sign-up server, the tournament manager, or the referee.

Failures in automated players—an external player or one of the company’s “house players”—are examples of non-critical failures. All player may send a response that is illegal according to the rules of the game; human players accuse each other of cheating in such cases. A “house player”—really all logical players—may raise an exception or may corrupt the referee’s data representations, depending on the chosen programming language and the logical communication protocol. In the case of remote players, a failure will take one of three forms: a lack of a timely response, an ill-formed response, or a well-formed response that is invalid with respect to the context.

game server tournament manager player player interface: logical remote referee

game pieces  (cards, destinations,  connection map, rails) game observer observer interface: logical remote failure discovery

Figure 14: The discovered components

Likewise, failures in observers should be considered non-critical. While observers typically do not respond—meaning the communication is basically one-way—it is still possible for observers to crash and close a connection; to accidentally raise exceptions; and so on.

Since it is the manager and the referee that communicate with the automated players and observes, it is those that must discover failures and react. The reaction may differ from component to component, from protocol to protocol. Given that failing player components—external or internal—are potentially dangerous to the functioning of the system, one policy could be to ignore them. By contrast, a human operator may just re-launch an observer component in some sports bar after it has crashed and the game server could accept the registration of this new remote observer.

The discovery of failures may call for a component in its own right or an enrichment of the communication components. Planning the construction and programming them will show.

10.4 Construction Plan🔗

The process of making a construction plan starts with a listing of all discovered components and how they (might) depend on each other. For the second part, it is best to draw a graph of dependencies. This graph will then suggest layers of the software system and thus a preliminary construction plan. Turning these layers into an actual plan must take into account external constraints.

Figure 14 presents the requested list of discovered components in two columns. The entry for game pieces summarizes the need for four components, each data-representing a piece of information that corresponds to a physical game piece. Both the player component and the observer component interact with the game system at two levels: one for the logical data exchange and one for remote communication.

A close look suggests that the game-pieces components do not depend on anything else in this list, while, for example, the game server depends on almost every other component, directly or indirectly. Similarly, the manager must rely on the referee component to run each of the games in a tournament, meaning the former depends on the latter. Working through the whole list in this manner yields the graph of figure 15.

The figure also shows how this dependency graph naturally yields five layers. Each layer’s components depend on components in layers below but not on components in layers above the current one. As before, an arrow points from component A to component B means A can be developed and compiled only if B exists—or in terms of modules, if A imports B. Note that even though none of the components depend on the “failure recovery” component, its vertical positioning suggests that it might be omnipresent in many of them; as indicated already, its actual existence and dependencies are likely to be discovered during the development of the code.

Simply put, a construction plan arranges this graph in a linear order; technically, any topologically sorted arrangement might do. If a component A depends on B, the latter appears first in the list. Following this plan ensures that each component is properly tested before a developer moves on to components that depend on it. If a bug appears during the construction of a dependent component, the likelihood is high that it is in the component under construction, not those that already exist and are tested. Additionally, it is possible to formulate and run preliminary integration tests that exercise the flow of use cases from the highest layer in the graph to the bottom. Such preliminary integration test often reveal different kinds of bugs than plain unit tests.

Figure 15: Planning the game server; its dependencies

One key improvement over such a simple plan is to take into account external constraints. Examples of important constraints are delivery speed or demo sessions with investors, potential customers, focus groups, and so on. To pick an example for this particular case, an investor might wish to watch an individual game on a single computer to make sure the team is making progress. The next logical step is to run a demo for an entire tournament, again on a single computer. Finally, the investors will wish to see how tournaments are run on a bunch of computers, perhaps all in a single room. Eventually the company must also ascertain that a country-wide or world-wide distribution satisfies basic performance criteria.

In order to reflect these external constraints, the construction will proceed in three major phases. Each yields a prototype that illustrates progress on the basic ideas: local games, local tournaments, and remote tournaments. Once these goals are accomplished, the product will need performance tuning—something beyond the scope of a course project. Note how the first two phases are all about the game and tournament logic, while the last one deals with remote-communication concerns.

As at the end of phase 2, the company might wish to demonstrate the product again. While the tournament still runs on a single computer, an investor could observe it—if the team had thought of specifying a tournament-observer interface and a rendering component.

In general, just thinking about such external constraints at this stage reveals gaps in the analysis and the construction plan. See the next section for how to inspect analyses and plans.

Figure 16: The logical and remove client-server architectures

Phase 3: The Game Server The goal of the third phase is to break up the monolithic prototype into server-and-client pieces. Figure 16 contrasts the two view. While the left side shows the entire logical system running on a single computer—the bold boundary—the right side puts the clients outside of the game-server’s machine box.

11 Inspecting the Plan🔗

Between each of the three steps—context analysis, use-case analysis, and construction plan—developers should take a close look at the result of the step. While there is no code yet, it is still good practice to have a second pair of eyes, and even a few more, inspect the analyst’s thinking about the project. Just because there is no code, we can still speak of “software inspection”—component identification and construction plans are a part of the software product.

Let’s take a look at what could happen when a planner presents the diagram of figure 15 and the construction plan to his development team. The presenters would probably give a brief summary of the context analysis and then move to the diagram as the result of the component discovery. Most of the time would be spent on the construction plan, simply because the team is about to embark on the code developing phase of the project.

Let’s take a break here and reflect on the style and content of this dialog.

The style of the dialog illustrates egoless reviewing. Find all references to the artifacts (plan, components) and re-read the passage. None of them use “how do you check the rules” (or similar language) to discuss what the intended software is supposed to do, what attributes it should possess. Otherwise the participants would identify the creator and the creation, which injects unnecessary personal attributes into the conversation. Inspections of code or designs are not about their creators, only their products. Language reinforces this idea.

The content of this dialog is about a first planning issue. While it is clear that the presenters and the reviewers have discovered a potential problem, think about what kind of problem it is. For code, we think of design flaws and bugs. For pre-code designs, it is better to think in terms of “looking ahead” vs. “needed now” or about a component’s size and functionality versus functionality that is not at all allocated to a specific component. The discovery of a possibly overly complex component is the analog of a design flaw, and it is sometimes premature to address such issues at this stage. The discovery of a missing functionality allocation is definitely something that the team must incorporate into its work schedule as soon as possible.

Note how the creator of the construction plan has something specific in mind already plus a supportive rationale. Still, this design choice deserves an additional discussion at some point; see Interface Inspections, Systematically. For now, let’s resume this inspection.

Consider the difference between splitting off the rule checker from the referee and not having a component for representing the state of the game at all. Both pieces of functionality—checking rules and dealing with the current state of the game—are necessary. If we assume that each component is developed by a pair of developers, we immediately see a big difference, however. The pair assigned to the referee is going to discover the need for checking rules. They may decide that rule checking is simple and fits into the referee, or they may alert the rest of the team about the need for a separate component. By contrast, the state component isn’t even in the graph or on the list of components needed. The developers of the player interface are going to write signatures in terms of the state representation but they may not immediately see that the component is missing from the construction plan. The nature of disruption is quite different.

Figure 17: Fixing the construction plan for the game server

Figure 17 displays a revision of the dependency graph in figure 15, based on the feedback from the plan inspection. The diagram comes with a new layer for the component that represents the game state. It is in the middle between the “Foundation” layer and the “Games” layer. Almost all dependency lines go through this new module box, because it is likely to depend on the entire foundation and both the referee and the logical player component depend on it. Additionally, the referee component is modified to indicate that it may need a separate rule checker functionality.

Exercise 5. Describe at least two methods that the game-state component should implement: their signatures and their purpose statements. Also describe informally how they implement the functionality.

Exercise 6. Read up on the remote-proxy design pattern. Then imagine a dialog that inspects the layer at the top of figure 17 that discovers at least one missing component.

12 Why Inspections Matter Even If There is No Code🔗

Software development includes all steps from the initial conception to its realization as code. This applies equally whether a team works on a brand-new system, the repair of an old legacy system, or just the addition of a new feature.

In the distant past, software engineers insisted that these products had to exist before developers started coding. They had good arguments, but the emergence of (near) continuous software deployment has promoted agile and extreme programming approaches. These approaches push that programming comes first and code is the only “thing” that really exists. This book is agnostic about the two alternatives.

The Purpose In all likelihood, the purpose statement for a system or a feature and a contextual analysis is the result of a negotiation between “marketing” and the leader(s) of the development team. The latter translates the agreement into an actionable task, that is, something developers can actually implement. While a purpose statement should be written down and turned into a one-line slogan, the result of a contextual analysis may exist only in the heads of the negotiation team.

A clear purpose statement for software systems and their features, like the one in A Sample Project: Analysis, Discovery, Planning, helps the developer team focus. The leader and the team members can evaluate every new feature request with respect to the overarching purpose. If it doesn’t (seem to) fit, the statement should help the leader start a renegotiation process and articulate arguments in support of the changes.

Writing down the results of a contextual analysis—with sketches like those in figure 6 and component lists like in figure 14—helps both the current team and future maintainers. The discovered constraints and contextual peculiarities (may) help explain the organization of the system and particularly intricate pieces of code. The description is also going to help with planning future extensions and adaptations of the system.

The Plan A dependency diagram—or a set of dependency descriptions—is equally likely to be needed, and hopefully created, up front or during the coding process, when a first draft of the (essential) software has been developed. In either case, it needs adaptation as inspections uncover flaws and additional coding change the relationships or create new ones. If a team dives into coding without a dependency diagram, it should develop one as soon as any of its members expresses concerns about any relationship between components during a meeting or inspection.

Every new team member is going to welcome a dependency diagram. Imagine yourself joining a team, being assigned a feature ticket, and staring at dozens of files and modules in the code base. Where to begin. A dependency diagram, such as the one in figure 15, will greatly facilitate the navigation of the code. If the components come with short purpose statements, a new team member can quickly hone in on the places where code has to be adapted or added. By using the relationships, a maintainer can also inspect functionality in use contexts, which may explain oddities in the implementations of some piece of functionality.

12.1 Documents: Start the README, Before the Coding Begins🔗

These steps may have taken place in informal manner, with conversations near white boards in a meeting room, using napkins in a coffee shop, or some other form like that. In some settings—say a safety-critical project concerning a nuclear reactor—someone will be asked to turn those discussions into formal documents. In other settings—a start-up whose founders are impatiently waiting for code so that they can run demos—nobody may wish to take the time. But even in these latter settings, someone should preserve whatever was written down. At a minimum, someone should take pictures with a cell phone and collect those in a project repository. Getting started with the README is the hard part, but it is critical to make the development socially responsible.

Once the repository is created, it makes sense to add a document that guides future readers through its files. In many cases, people call this document a

README file

and the joke is that this file is the best place to hide secrets. The problem with such read-me files is that they are often an after-thought. Someone may remember late in the creation process that such a document should exist, and it is compiled in a rushed manner, yielding an incomplete and possibly uninformative content. If such a file is created at the very beginning, is thought of as a guide to the project, and is updated regularly, it may just help future maintainers understand the big picture behind the project, its pieces, and their relationships.

Once someone has performed a context analysis, identified components, created a construction plan, and documented this all in a README file (or several), it is time to tackle what most developers think is the key task—coding—but which we now understand is just a part of the overall software product and the software development process.

Exercise 7. Distill the sample project from the preceding section into a README file. It is okay to take pictures of the diagram in this book, but use your own words to describe what’s going on.