---
title: "Code documentation"
source: The Turing Way
source_url: https://github.com/the-turing-way/the-turing-way
licence: CC-BY-4.0
domain: data-and-analysis
subdomain: turing-way
date_added: 2026-04-25
---

(rr-documentation-code)=
# Code documentation

It is a good practice to document the source code of software regardless of how time consuming it may be. 
The goal of code documentation is to provide context and explanations for the source code. 
This way others can understand why a piece of software exists, how it was built and how to use it or reuse it.

## Extended Software Documentation

Documenting software may require you to prepare extensive descriptions of the key aspects of software, 
such as explanations about how to start using the software, or examples of how to use the software for particular tasks. 
What to document will be different for each software, and how to document it will be different for each audience.   
Below, there is guidance on how writing extended software documentation can be approached.

(divio-documentation-system)=
### Diataxis Documentation Framework
When extended documentation is necessary, common questions are: What to document? and 
How to organise documentation concisely?
To answer such questions, Daniele Procida proposed the [Diátaxis documentation framework](https://diataxis.fr/) to organise software documentation.
The system distinguishes between four types of documentation: tutorials, how-to guides, explanation and reference.

* **Tutorials** aim to teach others how to use the software by describing things step by step.
For example, how to navigate the graphical interface of software $X$.
* **How-to guides** describe the specific steps required to solve particular problems with the software in question.
For example, how to find research dataset $A$ in the data archive $B$, using software $X$.
* **Explanations** aim to create understanding by providing context to relevant topics for the software.
For example, if software $X$ implements a [quickSort algorithm](https://www.geeksforgeeks.org/quick-sort/) to find a value in a lists of integers,
it might be relevant to include an explanation about why that algorithm was chosen and how such algorithm operates.
* **Reference guides** describe the code and how to use it. 
They should include  descriptions of functions, fields, attributes, methods and APIs, and how to use them.
For example, if software $X$ includes a function $S$ that adds two numbers. 
A reference guide for $S$ should describe what inputs it expects, what outputs it produces and in which cases it can or cannot be used. 

### User's Documentation vs. Developer's Documentation

Another way to think about software documentation is to distinguish between the documentation for the end user of the software, 
and the documentation oriented to describe the insides of the software to other developers. 
This approach for organising documentation is simpler than [Divios Documentation System](#divio-documentation-system), 
but it does not offer further guidance about how to distinguish which aspects of software documentation are relevant for an end user and which are relevant for a developer. 
It is up to the developer's experience to decide what content is relevant and for whom.
The table below offers some examples on what might be included as user and developer documentation.

| User Documentation | Developer Documentation |
|----------|----------|
| Installation instructions  | Development setup  |
| Default settings  | How to run tests  |s
| Tutorials | Development roadmap |

> Regardless of which approach is used to document software. The bottom line is 'some documentation is better than no documentation'

## Code Comments 

Some software documentation can be written directly as part of the source code using **code comments**.
Code comments can be included as *block comments* or *inline comments*. 
They are used to explain what some pieces of code do, or to explain why something in the code was done in a particular way. 
A good practice is to comment only what is necessary, and not to aim to comment each single line of code. 

How to write code comments depends on the programming language and the codinging styles that one wants to follow. These are some references relevant for writing code comments.

- [Best practices for writing code comments](https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/)
- [Docstrings Converntions for Python](https://peps.python.org/pep-0257/)
- [Creating docstrings in R](https://josephcrispell.github.io/2021/07/26/creating-R-docstring.html)
- [](#rr-code-quality-readability)
