Design Document

Design documents are essential in industry. When given a new project, engineers usually write a document and present it to their team before or during the implementation, to get discussion and suggestions. For this class, your design document (design.md) should be a concise design rationale for the changes you made. See the sample design document for an example.

In design.md, discuss the options for how you could implement these changes, what the tradeoffs are, and why you chose your implementation. Keep in mind our goals of maintainability, readability, and extensibility. Include the following:

  1. An overview of the change and relevant code structure
    • Briefly describe the feature or bug fix and the relevant part of the codebase.
    • Explain the main files, classes, functions, or data flow involved in your change.
  2. Diagrams
    • Create a diagram that shows how the relevant parts of the code base relate to each other. The purpose of the diagram is to help a coworker understand the code you worked on and which methods and classes you changed. UML and C4 diagrams are common choices, but for Assignment 1 you can use any visual that communicates this clearly. You are not expected to know UML or C4 yet.
  3. Identify and describe the key design decisions that you made during the project. This may be decisions such as where to add code, how to decompose the code into classes and functions, how a value is passed between functions, etc. There may be one or many such design decisions, depending on the task.
    • What problem you were solving.
    • What options you considered.
    • The tradeoffs of each option.
    • Why you chose your final approach.