Sharing Research Code: Messy Code Beats No Code, and Here's How to Do It

The methods section says “data were analysed with linear mixed models in R.” One sentence, sitting on top of 600 lines of code and dozens of decisions: which variables were standardised, how the random effects were structured, what happened when a model failed to converge. Nobody can reproduce an analysis from one sentence. The code is the full methods section.

The most common reason for not sharing is “my code is ugly”. The good news is that readers do not need beautiful code. They need code that runs and is clear enough to follow.

The threshold for good enough

• It runs end to end on the data, or on simulated data if the real data cannot be shared.
• It produces the tables and figures in the paper, with file names or comments showing which script generates which output.
• It has a README explaining requirements and how to run it.
• It contains nothing sensitive.

Not required: speed optimisation, turning it into a package, a comment on every line, automated tests. Those are nice, but they are not conditions for sharing.

A minimal README

1. One-line description: which paper this code reproduces, with its DOI once available.
2. Requirements: software and versions, such as R 4.4 plus package versions, or a renv.lock or requirements.txt file.
3. Data: where to get it and which folder to put it in; if restricted, how to request access.
4. Run order: 01_clean → 02_models → 03_tables, with rough run times.
5. Output map: Table 2 comes from script 03, Figure 1 from script 04.
6. Licence and how to cite.

The output map is the item most often forgotten and the most useful: people checking your work usually care about one specific table.

Remove what must not leak

Before pushing to a public repository, check for:

• API keys, database passwords, tokens: move them to environment variables or a config file that is never committed. If one has already been pushed, deleting the file is not enough because version history keeps it; revoke and replace the key immediately.
• Paths with names or machine details: “/Users/jsmith/…” leaks information and breaks on every other computer.
• Personal data embedded in code: lists of participant IDs used for filtering, comments like “drop Anna, she left the course”.
• Intermediate output files that may contain individual-level data.

A simple trick: make a clean copy of the folder, delete everything not needed, and run it from scratch. If it works, that copy is what you publish.

Choosing a licence

Code without a licence legally gives nobody permission to reuse it. Note that Creative Commons licences are designed for content and data and are not recommended for software.

Check your institution's intellectual property policy and funder terms first; some have specific rules about software written by staff.

Where to store it: a working repository and a frozen archive

GitHub and GitLab are good working homes, with version history and a way for others to report problems. But accounts get deleted and repositories get renamed. So when you submit, create a frozen archive:

• Link your GitHub repository to Zenodo and create a release; Zenodo archives that snapshot and issues a DOI.
• Or upload a zip file directly to Zenodo, OSF or your institutional repository.
• In the paper, cite the archive DOI, not just the GitHub link.

Reviewers and readers need the exact version that produced the published results, not whatever you changed afterwards.

Getting code and software cited

Add a CITATION.cff file to your repository and GitHub will show a “Cite this repository” button. In your paper, cite the key packages you relied on; many R and Python packages provide a citation (in R, run citation() with the package name). The people who wrote the tools you depend on deserve credit just like the authors of a paper.

Writing the code availability statement

• “Analysis code reproducing all results is archived at Zenodo (DOI: …) under the MIT licence.”
• With restricted data: “Analysis code is available at … Because of ethical restrictions the original data are not public; the repository includes simulated data with the same structure so the code can be run.”

The simulated-data option is more valuable than many people realise: checkers can confirm that the code does what the paper describes without ever seeing the real data.

An afternoon plan

1. 30 minutes: make a clean copy, strip sensitive information, convert absolute paths to relative ones.
2. 60 minutes: rerun from scratch, fix what breaks, record package versions.
3. 30 minutes: write the six-part README, add a LICENSE and a CITATION.cff.
4. 30 minutes: push to a repository, create a DOI-bearing archive, put the DOI into the manuscript.

Your next step: pick your most recent paper with an analysis and run through these four steps for it. Next time, you will set up this structure on day one and it will cost almost no extra time.

Câu hỏi thường gặp