Code documentation

Good code documentation acts as the bridge between developers and users by clearly explaining the functionality and rationale behind your code. Whether you’re writing inline comments or structured documentation, the key is to make your code readable, maintainable, and accessible to both current and future contributors.

Python projects

Code comments, docstrings, API reference.

Learn more »

MATLAB projects

Documenting MATLAB projects.

Learn more »

R projects

Documenting R projects with roxygen2.

Learn more »

Types of source code documentation

1. Code comments are inline annotations meant for developers who read or maintain the source code. They are useful for clarifying complex parts of code, noting why certain decisions were made in specific blocks or lines.

TipGood code comments should:

• explain parts that are not intuitive from the code itself
• explain the purpose of a piece of code (why over how)
• need to be kept up-to-date as wrong comments are not caught through testing
• not replace readable and structured code
• not turn old code into commented zombie code (see code smells)
• not repeat in natural language what is written in your code

2. Docstrings (or equivalent structured documentation comments, e.g., #' roxygen blocks in R) provide a description of the function, class, or module that follows immediately after it. They should contain all the relevant information needed for using them, rather than explaining how the code works. Docstrings are available to users without looking at the source code (as opposed to comments) and can be used to generate user documentation.