Code sharing checklist

Work through this checklist before you publish and share your data-analysis repository. Unfold the info boxes if you need more tips, examples, and links.

Note

Note: The list below is by no means exhaustive. There are always other solutions and options. So if a proposed solution does not fit for your project, that doesn’t mean you are doing something wrong.

If you have suggestions on other checks that I forgot, or solutions that you think work well, feel free to edit this page on Github.

These are the checks from the “Good practices for sharing research code” session.

Structure & orientation

• Separate your files into folders Most importantly: Separate data, code, and output. Raw data stays read-only in its own folder; your scripts produce the cleaned data and the outputs.

Details

There is no single “right” structure, the important thing is that it’s clear and consistent. A simple example:

temperature-resistance/
├── data/
│   ├── raw/      <- read-only
│   └── clean/    <- made by the code
├── analysis/
└── output/

You can also look at the structure of other repositories in your field or check out some templates like rrtools (R) or Cookiecutter Data Science (Python).

• Give files informative names File names should reveal the content, have no spaces or special characters, with left-padded numbers or dates (YYYY-MM-DD) as a prefix.

Examples

Avoid	Prefer
analysis final.R	02_fit-models.R
data.csv	2024-03-11_growth-assay.csv
Rplot01.png	linear-model-fit.png

More: Jenny Bryan, How to name files.

• Write a thorough plain-text README The entry point to your project, in plain text or Markdown.

What a README should contain

A readme should answer at least the following questions:

• What the project is, and which paper it belongs to
• How to run it: install steps and the order to run the scripts
• How files are structured: what is in each folder
• How to cite it, and who to ask when it breaks

This is a minimal template in Markdown format:

# Project title

Code and data for <paper citation>, doi:...

Cite as: <code citation>, doi:...

Contact: <name> (<email>)

## How to run
1. Restore the environment (renv / uv)
2. Run main.R / main.py

## Project structure

Describe the folders and files

Running the code

• Make the run order obvious Number your scripts, or add a main.R / main.py that runs everything in order.

Options to show the run order

1. Numbered scripts (01_, 02_, …) plus a “How to run” section in the README
2. A main script that calls all other scripts in order (put it at the project root). This will be the only script that users have to open.
3. A workflow tool that reruns only what changed: targets (R), Snakemake (any language)

For most projects, option 2 is a pragmatic choice.

• Record dependencies and versions Include the language version and a list of all packages/libraries and software your code depends on. Use a lockfile so others can recreate the environment.

Tools to record dependencies

• R: renv (init / snapshot / restore)
• Python: uv (uv add, uv sync)

Don’t forget to state the language version too (e.g. R 4.4.1, Python 3.12).

• Use paths relative to the project root No absolute paths, no setwd()

How

Run from the project root and build paths with here (R) or pathlib / pyprojroot (Python). Avoid setwd("C:/Users/...").

• Set a seed for anything random Sampling, bootstrap, permutation, simulations, etc. all reproduce only with a fixed seed.

How

set.seed(42) (R), or rng = np.random.default_rng(42) (Python, preferred over np.random.seed()).

Data

• State the data situation in the README Open, restricted, or synthetic: say which, and how to get the real data if it is not included.

Three honest paths

• Too big: link to a data repository; include a small sample so the pipeline runs
• Restricted: say how to request access; keep a codebook so the code can be reviewed
• Closed: ship synthetic data plus the code that generated it

• Add a data README Document every variable: name, meaning, unit or coding, and missing-value codes.

Where and how

One data/README.md for the data folder, one table per file:

Variable	Meaning	Unit / coding
temp	Incubation temperature	°C
resistant	Grew on antibiotic plate	0 = no, 1 = yes

• Use open, non-proprietary formats .csv, .tsv, .txt, .json, .parquet rather than .xlsx, .sav, .dta.

License & citation

• Add a license Good standards are CC0/CC-BY for data and MIT/GPL for code

Which license to choose?

• Code: MIT (permissive) or GPL v3 (copyleft)
• Data: CC0 (public-domain waiver) or CC BY (attribution required)

Add a LICENSE file at the project root, and use choosealicense.com to copy-paste the text in there. Note that some licenses (e.g. MIT) require you to add a copyright line with your name and the year.

If you need separate licenses for code and data, put the data license in data/LICENSE and the code license in LICENSE. Then add a line in the README that explains which license applies to which files, e.g.:

All files in `/data` are licensed under CC-BY-4.0, all other files are licensed under MIT. See `data/LICENSE` and `LICENSE` for details.

• Make the project citable Add a “How to cite” line in the README, ideally with a CITATION.cff.

How

You can just add a simple “How to cite” section in the README.

But a nice touch is:

Build a CITATION.cff with cffinit and add this file to your project root. GitHub then shows a “Cite this repository” button, and Zenodo reads it when archiving.

Don’t forget to add your ORCID, this way Zenodo can link your code to your other research outputs.

Before you publish

Some last checks before you publish your repository.

• Remove all junk files Check if there are any file that should be deleted before publishing

What to look for

• Junk: .DS_Store, .Rhistory, __pycache__/, … (a .gitignore keeps them out by default)
• Old scripts or data files that are no longer needed
• Secrets / sensitive data: API keys, passwords, .env, unpublished or personal/patient data

• Run the project on another machine Practical reproducibility check: Send it to a colleague or another computer and try to run it from start to finish

Archive & publish

• Archive a version and get a DOI GitHub is not an archive. Release a version and archive it to get a citable DOI.

How and where

Common archives are Zenodo, Dryad, and Figshare. Upload your project and get a DOI.

For GitHub Users: You can archive a specific version of a project on Zenodo directly from GitHub: GitHub → Zenodo guide. This is a very popular combination, because it allows you to keep your project on GitHub and still get a DOI for a specific version.

• Put the DOI in the README and the manuscript So readers can find the exact version behind the paper.