index.qmd

---
image: static/img/hsjd-hall.jpg
---

Modern scientific projects are **sofware projects** (not *only* software projects). Bad scientific software and programming practices lead to:

- **Lack of computational reproducibility**: scripts cannot be run or different results are generated by other people or from other machines.
- **Wasted efforts and time** trying to fix or optimize buggy code.
- **Lack of trust** in obtained results.

When programming, **think of other people** who might need to understand and run your code (you in the future, collaborators, reviewers, etc.). **Good programming practices** are a set of somewhat general guidelines to follow in order to make your code better (less prompt to errors, more reproducible, easier to understand). Here are some examples:

- Consistent file and directory management
- Transparency
- Documentation
- Tidy and readable code
- Educated coding

There are many guides that cover these and more in detail, with particular applications for specific programming languages. Check [{{< fa brands github >}} dereknguyen269/programing-best-practices](https://github.com/dereknguyen269/programing-best-practices) for a repository of guides.

This handbook is aimed at members of the **NeuroDevelopment and Comparative Cognition (NeuroDevCo)** research group at Institut de Recerca Sant joan de Déu who want to **expand their knowledge about good scientific and programming practices**,  adhere to **common guidelines** established by fellow members in of group. The ultimate goal of this resource is to **facilitate collaboration and good standards**. 

# At NeuroDevCo {.unnumbered}

## Creating and sending code

1. Create a new, separate folder every time you share a script(s).
2. This folder should contain only necessary files, and all necessary files to run the script(s).
3. If necessary, sub-folders with standard names are created (e.g. `data`, `img`) (see @sec-files).
4. Create a virtual environment for the folder (`uv` in Python, `renv` in R) and activate it (see @sec-venv).
5. Write or move your script in the folder. Make sure you follow good programming practices (see @sec-coding).
6. Document the folder (e.g., README file) and the script (good comments) (see @sec-documentation).
7. Test your script(s), make sure they work as intended (see @sec-testing).
8. Register the installed packages (`uv.lock` in Python, `renv.lock` in R) and make sure the output file is generated (see @sec-venv).
9. Compress (zip) the folder. Change its name to the format `[yyyy-mm-dd]_[x].zip` where `[yyyy-mm-dd]` is the current date in the year-month-day format (with leading zeroes for single digits, e.g., `2025-05-01`) and `x` is a concise, meaningful, and consistent title for the folder (I recommend somwething like `study-name_description`, e.g., `2025-01-02_mop-newborns_preliminary.zip`) (see @sec-naming-files).
10. Upload the folder the OneDrive folder suggested by your collague(s).

## Receiving and running code

::: callout-important

Make sure you have a **compatible Python or R installation**. As a group, we should make sure to use the same version of each programming langugae, and to upgrade together for consistency. Each project should always have the same version of the programming language, unless decided so by everyone involved.

:::

1. **Download and unzip the folder** in the desired location in your machine. Try to be consistent, keep folders from the same study in the same folder, and avoid simply saving folders in your Desktop, or Downloads folder.
2. **Open your IDE** of preference (e.g., **Positron**) and open the project folder (see @sec-ide).
3. In the terminal/console prompt, **create a new virtual environment** from the provided `uv.lock` in Python (run `uv sync` in your terminal/command promt) or `renv.lock` in R (run `renv::restore()` in your R console) (see @sec-venv).
4. Read the documentation and follow the instructions to run the scripts, and go ahead!

::: callout-note

## Recommended readings

- Vuorre, Matti. 2025. “How I Work on Computationally Reproducible Academic Projects.” August 22, 2025. https://vuorre.com/posts/workflow/. 
- Vuorre, Matti. 2024. “Preprints: A Quarto Extension and Website.” June 20, 2024. https://vuorre.com/posts/quarto-preprint-psyarxiv-zero/.
- Velásquez, Isabella and Velásquez, Gustavo. 2022. Setting up macOS as an R data science rig in 2023”. https://ivelasq.rbind.io/blog/macos-rig/. 

:::