Code Review

From plotting to publishable

Before sharing code publicly, we need to make sure it’s in good shape — not just working, but clean, clear, well-documented, and reproducible.

❓Structure — does the repo follow a logical layout?

❓README & documentation — is it clear what each component of the repository does and how to use it? Could a stranger run this independently?

❓Clean code — is the code free from hardcoded paths, dead or commented code, debug prints, TODOs, adhoc naming, inconsistent indentation?

❓Environment file — is there an up-to-date environment.yml or renv.lock?

❓No raw data, results or credentials — are sensitive files in .gitignore, and data in a data repository?

❓Licence — is there a LICENSE file with an appropriate licence?

❓Citable snapshots — are there citable, persistent versions of the code?

Code smells: Repository

Repositories that are not structured well can be difficult to navigate, understand, and reproduce. Common issues include:

🔀 Mixed functionality — data preprocessing, analysis and visualisation all tangled in one file. Hard to read, test, or reuse

🗃️ Raw data committed to Git — data belongs in a dedicated repository with its own DOI, not version-controlled alongside code

🕵🏼‍♀️ Cryptic structure or workflow — lacking environment files, licences, nested folders without a documented workflow

ImportantThese are not just aesthetic concerns — they can make it challenging to test, maintain and share the codebase.

Code smells: Code

Analysis scripts often prioritise functionality. Common issues that sneak in:

🗺️ Hardcoded paths — absolute file paths that only work on one machine

💤 Dead code — functions defined but never called; lines commented out and forgotten

📦 Unused imports — packages loaded but never used

📝 Missing documentation — functions with no docstring, steps with no explanation

NoteCode smells are usually identified through code reviews or static analysis tools, and fixing code smells is called refactoring. When working collaboratively, code reviews become a shared responsibility. GitHub gives us the tools to collaborate safely.

Adding collaborators

  1. Open your repository on GitHub
  2. Go to Settings → Collaborators
  3. Click Add people
  4. Search by GitHub username or email
  5. Set their role — Write is appropriate for most collaborators
  6. They will receive an email invitation to accept

In Practice

CautionExercises

3.1 Accept your invitation to collaborate on the shared manuscript repository

3.2 Clone the manuscript repository to your machine and open it in your IDE

3.3 Explore the structure — how does it differ from the bare-bones analysis folder from yesterday?