Back to HomepageCredit: public domain
In Homework 3, you detailed what your software is going to do from a design perspective. All of those choices you made are about the problem you're solving with the software; those details concern the world. In this homework, you're going to specify how you're going to achieve those requirements, defining your software's architecture.
Unlike in building architecture, where there are standards for blueprints, there is no agreed upon way to specify architectures. There are highly formal tools which precisely detail the components and connectors of a system so that code can even be automatically generated from these architectural specifications (Shaw et al. 1995). Some architectural specifications are just vague sketched diagrams on a whiteboard (Cherubini et al. 2007).
One key idea in designing architecture is to imagine you're inventing new "species" of creatures. Unlike living species, however, which are concerned with survival, your components are entities that have responsibilities for storing data and accomplishing computation of some kind. Inventing new species is a creative activity; you want to think about what they will and won't do, give them names, and tell stories about how they interact with each other, exchanging data.
To capture your architecture, write a Markdown file in your GitHub repository that specifies all the components in your system. For each component:
In addition to details about individual components, write a natural language description of how the components interact, describing their connectors. (Are they communicating with events, function calls, timers, or other kinds of mechanisms?). If it helps clarity, create diagrams to specify these interactions.
While doing this, remember that the document you're writing is not intended to satisfy us. It's intended to help you organize, plan, and streamline your implementation efforts this quarter. Therefore, focus on writing a document that's useful to you. Think of the document like a big to-do list for all of the code you have to write.
Lastly, consider your process for writing your architectural specification. I recommend the following:
A lot of the work above can be delegated to individual teammates. Use your management structure to assign responsibilities to ensure the work gets done on time.
While you're producing a document, the real goal of architecture is to make sure everyone on your team has a consistent, detailed understanding of the architecture. If they don't, you'll end up with a ball of mud. To test this, quiz each other on the architecture you have planned: can each of you explain it in detail? If not, keep explaining it to each other until you have the same understanding in your heads and in your document.
Here is one example of a solid architecture description from a team in a previous year. It provided a detailed enumeration of components, clear explanations of functionality and data, and clearly-explained interactions between components. The document could have been even clearer by using diagrams to show interactions between components, and by providing more detail about the mechanisms that components would use to interact, but it's a good start.
Submit a GitHub URL to your architecture document in Canvas.
The most important qualities of an architectural specification are clarity and consistency. If something is ambiguous or inconsistent, your collaboration will be constantly interrupted by the need to clarify and you'll likely write code that you have to discard or change because of your misinterpretations. To incentivize you writing a clear, consistent document, for every unclear or inconsistent detail include, your team will lose 0.1 points. I'll give you three free ambiguities before I start deducting points (all documents have some ambiguities).
Shaw, M., DeLine, R., Klein, D. V., Ross, T. L., Young, D. M., & Zelesnik, G. (1995). Abstractions for software architecture and tools to support them. IEEE Transactions on Software Engineering, 21(4), 314-335.
Cherubini, M., Venolia, G., DeLine, R., & Ko, A. J. (2007, April). Let's go to the whiteboard: how and why software developers use drawings. In Proceedings of the SIGCHI conference on Human factors in computing systems (pp. 557-566).