Naming Objects

Naming variables is one of the most important things to get right to make your code readable and understandable to future readers of the code (perhaps even yourself!). Having a system for creating names also makes it easier to come up with new ones.

Mazama Science packages embrace lowerCamelCase for object names.

With the casing settled, we use an ornithologist’s sensibility for how to identify things:

• What is it? — a bird
• What kind of bird is it? — a blackBird
• What kind of blackBird is it? — a redwingedBlackBird

It’s a simple system: start with a noun and prefix it with descriptors until it is uniquely identified.

In this system we would never have a variable called: num_hours. Instead we go through our process:

• What is it? — (Hmm. What noun describes this? Ah yes!) — a count
• What kind of count is it? — (It’s not a “head count” or a “body count”.) It’s an hourCount.

For complex objects it is often helpful to give readers of the code a hint as to what type of object it is so they will know how to work with it. We often use variable names like:

• monitor — a mts_monitor object

We occasionally use ‘_’ to create classes of similar variables that are otherwise hard to name, e.g.:

QC_negativeValues

Naming Functions

Most functions should strive to be atomic in nature and should do one thing really well. Think of them as individual Lego bricks that we click together to achieve more advanced functionality. Where objects are well described nouns, functions are well described verbs that describe what they do as in:

monitor_collapse()
monitor_combine()
monitor_dropEmpty()
monitor_filter()
monitor_filterDate()
monitor_select()
...

All of these functions begin with monitor_ because they are for creating or working with monitor objects. Many of these functions accept a monitor object as their first argument and return a modified monitor. This means that they can be used with the %>% “pipe” operator and chained together as in:

Sacramento_area_daily_avg <-

  # Get all data for 2018
  monitor_loadAnnual(2018) %>%
  
  # Filter to a 2-week period
  monitor_filterDate(
    startdate = 20181108,
    enddate = 20181123,
    timezone = "America/Los_Angeles"
  ) %>%
  
  # Filter to monitors near Sacramento
  monitor_filterByDistance(
    longitude = -121.4931,
    latitude = 38.56844 ,
    radius = 50000
  )  %>%
  
  # Combine by averaging hourly values from different monitors
  monitor_collapse() %>%
  
  # Calculate local time daily averages
  monitor_dailyStatistic() %>%
  
  # Extract daily average values from 'monitor' object
  monitor_getData()

Naming Files

Each file should contain a single function of the same name. Thus, the function named monitor_filterDate() is defined in monitor_filterDate.R. An exception is made for small, mostly internal functions used in conjunction with a particular type of object or activity. These can be stored together in a file named utils-~:

utils-monitor.R

Syntax

We generally adhere to the Wickham Style Guide for syntax with a few exceptions:

if ( <logical expression part1> && <logical expression part2> ) {
  ...
}

  # Filter to a 2-week period
  monitor_filterDate(
    startdate = 20181108,
    enddate = 20181123,
    timezone = "America/Los_Angeles"
  ) %>%