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
  • DO: everything created by humans, small data inputs
  • DON’T: things created by the computer from your inputs (generated files; those will be reproduced via a workflow). Also do not version large data inputs.
• 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.

Tip

• 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).

Tip

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:

• Python
• R/R Studio
• Stata