[style, optimize, definition, human]

Write programs for people, not computers

Make your code easy to understand for humans. If your code looks very complex or messy, you’re probably doing it wrong.

  • Organization
    • Define functions that do one mayor step each, instead of one giant script doing everything
    • Write short scripts that do one task each
    • Document only what your code doesn’t say, but nothing else
  • Style
    • Use meaningful and short variable names
    • Use consistent code and formatting styles (oneExample, one_example, example-one)
    • Make use of indents in your code

Define things once and only once

Let computers repeat and execute tasks.,

  • Rule of 3: if you copy-paste code 3 times or more, write a function instead.
  • If you do things often, automate them
    • e.g., by using scripts, macros, aliases/variables
    • write a dictionary with definitions
  • Use build tools to automate workflows

Use a version control system

  • Add all inputs, but no outputs/generated files
  • Work in small changes
    • Create snapshots/commits in small and logical steps. This will allow you to go back in time if necessary, and to understand progression.
  • Use an issue tracking tool to document problems (e.g., such as the Issue tab on GitHub; email is not an issue tracker!)

Optimize software only after it works correctly

Even experts find it hard to predict performance bottlenecks.

  • Get it right, then make it fast
  • Small changes can have dramatic impact on performance
  • Use a profile to report how much time is spent on each line of code

Be a good code citizen

  • Team members should take the time to improve code they are modifying or extending even if they did not write it themselves.

  • A core of good code plus a long series of edits and accretions equals bad code.

    • Why? The logical structure that made sense for the program when it was small no longer makes sense as it grows.
  • It is critical to regularly look at the program as a whole and improve the logical structure through reorganization and abstraction. Programmers call this refactoring. Check this link to learn how to implement refactoring.

  • Even if your immediate task only requires modifying a small part of a program, we encourage you to take the time to improve the program more broadly.

  • At a minimum, guarantee that the code quality of the program overall is at least as good as it was when you started.

Keep it short

  • No line of code should be more than 100 characters long.
    • All languages we work in allow you to break a logical line across multiple lines on the page (e.g, using /// in Stata or ... in Matlab).

Set your editor to show a “margin” at 100 characters.

  • Functions should not typically be longer than 200 lines.

Language-specific style guides

Want to learn language-specific coding guidelines? See the following building blocks for: