2  Documenting your code

Documenting your code is crucial for both your future self and anyone else who might work with your code. Good documentation helps others (and your future self) understand the purpose, functionality, and usage of your scripts. You want to document your code in the same way that you would write a detailed lab notebook.

For more in-depth guidance, see A Guide to Reproducible Code in Ecology and Evolution. While the examples are mainly in R, the principles are general and apply across programming languages.

To see how code documentation looks like in a real-world context, have a look at an example workflow I wrote for a previous analysis. It shows how to describe each analysis step, software dependency, and command used in a way that allows someone else to reproduce the entire analysis from scratch and for me to remember what I did a month later:

This workflow documents a 16S rRNA gene amplicon analysis from Winogradsky columns, including:

Even if you don’t understand all commands yet, notice how it reads almost like a lab notebook for code where each step has context, rationale, and description of the results.

2.1 Choosing your editor

2.1.1 Plain text editor

Avoid visual editors like Word, as they are not designed for code and can change syntax by, for example, replacing backticks (`) with apostrophes (').

One of the easiest solutions is to use a plain text editor, such as:

  • TextEdit (Mac)
  • Notepad++ (Windows)

These editors allow you to write and save code safely, but they lack features like syntax highlighting or integrated code execution.

2.1.2 Rmarkdown in RStudio

RMarkdown combines plain text, code, and documentation in one document. You can write your analysis and explanatory text together, then “knit” the document to HTML, PDF, or Word.

To create an RMarkdown file in RStudio:

  1. Go to File → New File → R Markdown
  2. Choose a title, author, and output format
  3. Write your code and text
  4. Click Knit to render the document

More info: RMarkdown tutorial

2.1.3 Quarto in Rstudio

Quarto is a next-generation alternative to RMarkdown. It supports R, Python, and other languages, and offers more output formats and customization options. Quarto was also used to generate this tutorial.

To create a Quarto document:

  1. Go to File → New File → Quarto Document
  2. Choose a title, author, and output format
  3. Click Render to generate your document

More info: Quarto documentation

2.2 Markdown for Documentation

Markdown is a lightweight language for formatting text in your plain text, Rmarkdown or Quarto document. You can easily add headers, lists, links, code, images, and tables.

Headers:

Use # to add a header and separate different sections of your documentation. The more # symbols you use after each other, the smaller the header will be. When writing a header make sure to always put a space between the # and the header name:

# Main Header
## Subheader

Lists:

Use - or * for unordered lists and numbers for ordered lists.

Ordered lists are created by using numbers followed by periods. The numbers do not have to be in numerical order, but the list should start with the number one.

1. First item
2. Second item
3. Third item
4. Fourth item 
1. First item
2. Second item
3. Third item
    1. Indented item
    2. Indented item
4. Fourth item

Unordered lists are created using dashes (-), asterisks (*), or plus signs (+) in front of line items. Indent one or more items to create a nested list.

- First item
- Second item
- Third item
- Fourth item 
 - First item
- Second item
- Third item
    - Indented item
    - Indented item
- Fourth item

You can also combine ordered with unordered lists:

1. First item
2. Second item
3. Third item
    - Indented item
    - Indented item
4. Fourth item

Code Blocks:

Enclose code snippets in triple backticks followed by the computational language, i.e. bash or r, used.

```bash
grep "control" downloads/Experiment1.txt
```

Some editors also use the following syntax:

```{bash}
grep "control" downloads/Experiment1.txt
```

Links:

You can easily add links to external resources as follows:

[Link Text](https://www.example.com)

Emphasis:

You can use * or _ to write italic and ** or __ for bold text.

*italic*
**bold**

Pictures

You can also add images to your documentation as follows:

![Alt Text](path/to/your/image.jpg)

Here, replace Alt Text with a descriptive alternative text for your image, and path/to/your/image.jpg with the actual path or URL of your image.

Tables

Tables can be useful for organizing information. Here’s a simple table:

| Header 1 | Header 2 |
| ---------| ---------|
| Content 1| Content 2|
| Content 3| Content 4|