Weecology's Wiki
Computing
Code Style Guide

Lab Style Guide for Code

Guiding Principles

This document provides a guide to code structure and formatting across languages used within the Weecology projects. Links to language-specific guides are provided below.

Generally, this guide follows the principles outlined here. In particular:

  1. Write and style your code for human readers
  2. Minimize the number of facts a reader is expected to hold at one time
  3. Use consistent, distinct, and meaningful names
  4. Employ consistent style and formatting

Structure

Modularize

  • Break code into chunks corresponding to contained tasks
  • Whenever possible write code into functions, even if the function isn’t called repeatedly

Loops

  • Loop should be used with repeated tasks unless you actually need the indices
  • If the language allows, use vectorized functions in place of loops to speed computation and reduce code volume

Style

Naming

  • Be concise and meaningful, but conveying meaning is more important than brevity
    • Document abbreviations if they are not common or immediately intuitive
    • Functions are verbs, variables are nouns
  • Use snake_case for variables and functions (e.g., portal_data)
    • Exceptions:
      • established prefixes (e.g., n in nobs to indicate the number of observations)
      • established suffixes (e.g., i in obsi to indicate the specific observation in a for loop)
  • Use UpperCamelCase for class names for object oriented programming (primarily in Python)
  • Do not use . in names (particularly in R)
  • Do not use single-letter names
    • Exceptions:
      • representing a term in an equation (e.g., y in y = m * x + b)
      • using an established name in a language (e.g., n references the number of draws from a random variable in R)
  • Constants, and only constants, should be in all caps

White space

  • spaces after commas
  • spaces around operators (unless inside the argument definitions in Python)
  • no spaces around parentheses

Line length

  • Lines <= 80 characters
    • But a few extra characters can be better than confusing contortions to make length
  • Parentheses/brackets/braces with breaks after commas are typically better than line break characters (but not always)

Indentation

  • Always indent to indicate that code is inside a function, loop, etc. (Python makes you do this. Thanks Python!)
  • Use spaces, not tabs (but it’s fine for you IDE to turn the tab key into spaces)
  • Follow language convention for number of spaces
    • R: 2
    • Python: 4
  • When breaking lines with parentheses (mostly in function calls/definitions) align with the leading character after the opening parenthesis
    (stuff, things,
 more_things)

References

  • Magic numbers (numeric references to elements, columns, rows, etc.) should be avoided.
  • References should be made by name or-in the case of loops-position.

Documentation

In-line commenting

External documentation

  • Use standard documentation comment styles
    • R: roxygen
    • Python: docstrings
    • These can create formatted documentation, but they are useful visual indicators even if you don’t do this

Language specific style guides