In the last lesson, you learned how to create a function in R. You learned that functions are efficient ways to reduce variables in your global environment. In this lesson your will explore that further. You will also explore function arguments.

The Function Environment is Self-contained

As discussed in the previous lessons, there are many benefits to using functions in your code including:

1. Functions make your code lesson complex by grouping sets of well-defined tasks into discrete lines of code.
2. Expressiveness - well named functions will make your code more expressive or self descriptive. As you scan the code, what it does is more clear.

However, functions also save memory by keeping intermediately created objects out of your global environment.

The function environment is self-contained. This means that when you run a function, it does not create intermediate variables in your global environment.

For example, in the previous lessons, you created a function called fahr_to_celsius. Within that function, you created two variables:

1. kelvin
2. celsius

Run the function below. Then call it fahr_to_celsius(15). Look closely at your global environment in R. Do you see the variables temp_k or result in your list of variables in R Studio?

fahr_to_celsius <- function(fahr) {
  kelvin <- fahr_to_kelvin(fahr)
  celsius <- kelvin_to_celsius(kelvin)
  celsius
}

fahr_to_celsius(15)

When you run the function above, it creates a new temporary environment where it runs the steps required to complete the tasks specified in the function. However, the variables defined by each intermediate steps are not retained in your global environment. These variables only exist within the function environment. This is convenient for you because each variable that you create consumes memory on your computer. It also reduces the “clutter” associated with too many variables in your global environment which could conflict further down in your code. For example you may have another variable called “celsius” in your code code further down.

Documentation

It is important to document your functions to:

1. Remind your future self what the function does
2. Show your future self and your colleagues how to use the function
3. Help anyone else looking at your code understand what you think the function does

Note that your written documentation can at best describe what you think the function does, because ultimately the code itself is the only true documentation for the what the function actually does.

A common way to add documentation in software is to add comments to your function that specify

1. What does this function do?
2. What are the arguments (inputs) to the function, and what are these supposed to be (e.g., what class are they? Character, numeric, logical?)
3. What does the function return, and what kind of object is it?

Like this:

fahr_to_celsius <- function(fahr) {
  # convert temperature in fahrenheit to celsius
  # args: temperature in degrees F (numeric)
  # returns: temperature in degrees celsius (numeric)
  kelvin <- fahr_to_kelvin(fahr)
  celsius <- kelvin_to_celsius(kelvin)
  celsius
}