How to Create a Plan

You've probably seen examples of planning in other domains all the time, in everything from building floor plans in construction to making a multi-year schedule for the classes you need to graduate. In fact, any time you've used a todo list to organize your approach to a large project, you've created and used a plan.

A plan helps you articulate the high-level structure of your solution to a problem. The plan may include information about different steps that need to be taken, as well as any ordering between different steps. Plans help ensure that your solution adheres to all of your instructions and constraints, before you invest a lot of work in a single step (whether that step is building a wall, taking a class, or writing a function). Then as you start working through our solution, you can look back at your plan to make sure you're on the right track.

Plans are also useful for communicating with others: architects and construction teams share plans to make sure everyone agrees on what needs to be built ahead of time. In programming teams, plans are also useful for making sure everyone agrees on what needs to get done. In this course, we have you write plans both so you can outline your steps and so that you can share your intended steps with TAs. With a written or drawn plan, TAs can help you determine whether errors in your code are at the level of code or the level of the plan.

These plans are not code! They are meant to be a higher-level overview of your solution. It's okay if a single step in your plan corresponds to multiple lines of code in your solution. If you find yourself identifying more than a handful of steps, consider trying to find a way to bundle some steps together. These bundles might help you to identify helper functions that you can write to make your code cleaner and easier to read. You may even want to create plans for these helper functions as well.

Samples

There are many different ways to represent these kinds of plans. In this document we will present a couple basic styles, but feel free to modify these or create your own!

Problem Statement

These sample plans are for the following problem from lecture:

Assume a school where students are assigned an advisor strictly based on the semester they're in. We have a table of students and a table of advisors, both with example tables below.

STUDENT TABLE

name	semester	SNC	quiz1	quiz2
Ursa	3	FALSE	83	56
Isaias	4	TRUE	92	79
Jackson	8	TRUE	61	0
Isi	7	FALSE	90	87
Thuy	5	FALSE	85	85
Brigida	5	FALSE	0	0

ADVISOR TABLE

sem	name
1	Pan
2	Greene
3	Greene
6	Pan
7	Rodriguez
5	Pan
8	Greene
4	Rodriguez

Part 1: Write a function that takes a student name as input and outputs the student's assigned advisor

Part 2: Write a computation that adds a new column of advisors to the student table

Plan Style 1 - Structured Text

Part 1

1. Find the row in the student table that matches the given student
2. Extract the semester from the row
3. Find the row in the advisor table that matches the extracted semester
4. Extract the advisor name from the row

Part 2

1. Build a column. For each row…
   a. Extract the semester from the row
   b. Find the row in the advisor table that matches the extracted semester
   c. Extract the advisor name from the row

Plan Style 2 - Shapes

Part 1

Part 2

Including Other Information

You are welcome to represent any additional information in your plan if it helps make the plan clearer for you or others reading it. Some examples:

• Adding type information
  • In Style 1, this might look like saying "The extracted value is a String."
  • In Style 2, this might look like labeling an arrow as String
• Giving names to the output values of specific steps
  • In Style 1, this might look like saying  "We will call this value student-semester."
  • In Style 2, this might look like naming an arrow student-semester
• Stating properties that must hold of your data at a certain point in the plan
  • In either style, this might look like writing "after this step, there will be exactly 1 advisor".

These pieces of information can be mixed together where appropriate. For example, I could label a named value with its type: student-semester :: String. What's most important is that you and others can read and understand the plan.