Code Standards

Best practices for source control, commit messages, documentation, & project management

Github source control

All code must be kept on GitHub. Be sure to commit and push regularly. Best practice is to commit several times a day when actively coding and push AT LEAST daily. The end of the workday is a great time to push. This serves three important purposes:

  1. It keeps us from losing track of our code if we overwrite a file or want to revert to an older version of a script. Every version of our code that has been committed and pushed can be retrieved if lost or overwritten. Code that has not been committed and push cannot be retrieved.
  2. Sharing our code lets us learn from each other and reuse code developed by other team members. If your repository is private, your code is only visible to those with whom you have explicitly shared it.
  3. It is very helpful for troubleshooting! When your code is online, it makes it much easier for other team members to understand the issue you are running into as they can see your entire repository, including the script with the problem. The GitHub version control will show the most recent version as well as allow exploration of any changes made to the script.

Git can be tricky and we’ve all had to deal with git problems. Please don’t hesitate to ask for help on Slack (#help) or search the web as there are many existing resources, such as this tutorial from GitHub. You will learn it eventually and we have a lot of expertise on our team available to help make your life easier. Many of us use Sourcetree or GitHub Desktop to manage our repositories.

Commit messages & descriptions

When you make a Git commit, include a short but meaningful message that describes the changes that you are committing. Typical changes include new functionality, improved code, updated parameters, bugfixes and corrections among others. The commit message should provide information on type and reason of edits made (i.e., what changes did you make since the last commit?) and why (e.g., is this fixing a problem, adding new functionality, etc.). These commit messages can be short and to the point but should be helpful to you and others who may be going through the repository in the future. More advanced use allows for writing pull request messages when working from a developer and a clean master repository and you can read more about it once familiar with the basics of Git

Managing your project

It is important to keep detailed notes for your project including design, progress, and analyses. The notes should be as comprehensive as possible to show so you can keep track of methods, changes you make, etc. By including all these details, you will be better equipped to make forward progress rather than going in circles and to eventually publish your results. A few key points:

  • It is never too early to start your project notes! You should start them as soon as you begin a project, so you have details from the entire process.
    • There are many different platforms that you can use to take your project notes depending on your preferences. Team members often use Word or Rmarkdown but there are other notes apps that can be just as effective. It is preferable to take online notes as they are both searchable and shareable.