Code Guide

The primary goal of your coding style should be clarity. We want other people and your future self to be able to easily understand what you wrote.

LJ Ristovska wrote a nice language-agnostic programming guide.

Language-specific style

• Stata
  • We generally should follow the Gentzkow and Shapiro Stata style guide, with the following exceptions:
  • We do not use their save_data or mmerge commands.
• Julia
  • We follow the JuliaPraxis style guide and QuantEcon style guide.

General naming convention

Variables

• Variable names should be lowercase:
  • 🆗 county_fips
  • ❌ County_FIPS, CountyFIPS, CountyFips, countyFIPS
• Variable names should be descriptive:
  • 🆗 state_fips, gas_flare_rate
  • ❌ sfps, gf_rate
• Variable names should be underscore separated unless they are short and it is clear:
  • 🆗 unemployment_rate_over_65, aqilevel, aqi_level
  • ❌ unemploymentrateover65
• Prefer clarity to brevity
  • 🆗 state_fips
  • ❌ s_fips
• Prefer specificity to generality
  • 🆗 nightlights_luminosity
  • ❌ nightlights
• Be consistent
  • 🆗 county_fips, state_fips
  • ❌ county_fips, fips_state

Functions/programs (Stata name for a function)

• Function and program names should be verbs describing what they do
  • 🆗 clean_birds
  • ❌ bird_cleaning, bird_cleaner
• Function names should be lowercase:
  • 🆗 clean_birds_data
  • ❌ CleanBirdsData, Clean_Birds_Data, cleanBirdsData
• Function names should be underscore separated unless they are short and it is clear:
  • 🆗 analyze_nightlights_birds, cleanbirds
  • ❌ analyze_nightlights_birds
• Prefer clarity to brevity
  • 🆗 clean_birds
  • ❌ cln_brds
• Prefer specificity to generality
  • 🆗 analyze_nightlights_birds
  • ❌ analyze_data
• Be consistent
  • 🆗 clean_nightlights_data, clean_birds_data
  • ❌ clean_data_birds, clean_nightlights_data

Spacing

• Use one space before and after a single binary operator or a comparator.

  • 🆗 this + that, this | that, a >= 0
  • ❌ this +that, this|that, a>=0
  • Spacing around ^, /, or * is optional.

• Use a space after a comma

  • 🆗 run_regressions(data, fixed_effects)
  • ❌ run_regressions(data,fixed_effects)

• Do not use a space after a unary operator or % when used to force a type.

  • 🆗 negative_id = -id
  • ❌ negative_id = - id

• If you are going to align vertically, prefer to align on the =.

• If the left-hand-side name lengths vary greatly in subgroups, align subgroups on the =.

• Prefer to split a long line after =, ,, ||, &&. or (.