Transitioning from Plans to Code

In the PCIP System, we first create a plan that details our goal(s), needs, and the steps to take to achieve our goals. Once we have a plan, we can move to coding. The transition from plan to code can be a difficult place to be in. Often times, this is where programmers lose sight of their goal as they start to ignore their plan and focus too much on the details of their code.

One approach we can take to help us avoid such pitfalls is to create a transition document instead of immediately starting coding. A transition document lives in-between our written plan and the first completed script. We create a transition document but first opening up a blank script file. We then begin to add comments to the script file that correspond to our plan. These comments create a structure to help us stay organized and not lose sight of our plan while we code. Once we have the transition document created, we can then fill in the transition document with our code to create the initial script.

Example

To help us get a sense of this, we can look at an example of a plan, transition document, and initial script for the height of a gummy bear problem from class. As a recap, here is an example plan for this context.

A Plan for Gummy Bear's Height Problem

Goal: Create a function that will tell me how high above the ground in centimeters a gummy bear is after a certain number of seconds have elapsed since launching the gummy bear from a spoonapult.

Needs: We will need the formula for telling us the height above the ground after some amount of elappsed time. For that formula we will need to know the acceleration due to Earth's gravity, the initial velocity of the gummy bear at launch, the initial height above the ground of the gummy bear at launch, and some way to represent the elapsed time since launch in seconds.

Now that we've seen the plan, we can take a look at the transition document and the initial script in a side-by-side layout. Notice that the transition document follows the structure of our plan. We used four dashes at the end of first-level comments (i.e., ----) to create headers (and entries in the auto-outline). We used second-level comments (starting with two hashtags, ##) to move key information from our plan to our scripting environment. Notice that we left extra space between different sections of our document; this helps to provide a bit of a buffer as we come back and work.

Transition Document

# Gummy Bear's Height Function ----
## Goal: Create a function that will tell us the height
## of a gummy bear above the ground any number of seconds 
## after being launch from a spoonapult



# Key Elements (needs) ----
## accel: -980.665 cm/sec/sec
## initial velocity: 350 cm/sec
## initial height: 71 cm
## elapsed time: seconds
 


# Define Function ----
## Pick Name
## List inputs/arguments
## 1/2*accel*time^2 + initial vel * time + initial height
      


# Test Function ----

Initial Code

# Gummy Bear's Height Function ----
## Goal: Create a function that will tell us the height
## of a gummy bear above the ground any number of seconds 
## after being launch from a spoonapult

# Key Elements (needs) ----
## initial velocity: 350 cm/sec, parameter intVel
## initial height: 71 cm, parameter intHeight
## elapsed time: seconds, variable t

# Define Function ----
findHeight <- function(t, intVel = 350, intHeight = 71) {
  h <- 0.5*(-980.665)*t^2 + intVel*t + intHeight
  return(h)
}

# Test Function ----
findHeight(t = 0.5) # should be 123.4169 cm

After completing the transition document, we can then go back to the top and start the coding process. Notice that the acceleration comment is gone; this is the result of us deciding to list this as a fixed, hard-coded value in our function. We also opted to define two parameters for the initial velocity and height values, using the provided values as their defaults. We also choose to use t as our variable to represent elapsed time.

Notice that we've replaced all of the comments in the Define Function section of our transition document. This is because we've carried those sub-steps out to create our function. We picked a name (findHeight), listed our variables (t) and parameters (intVel, intHeight), and used the formula as the rule of our function. We also added a test case.

A Note on Polished Code

We want to point out that the script shown as the Initial Code is initial code. That is to say, that there are additional things we could do in this script to make our function fully polished. A more polished version of our script might look something like the following, which is set up using roxygen style to create a documentation file for the function. Note: you are not expected to generate scripts like this in Stat 184.