The readability and documentation of code are important to make it understandable for others, but also for yourself. Otherwise, it may even be difficult to understand your own work at a later date, for example after a review by a specialist journal. As with a book, the readability of code is about how you write, organise and comment on it. In addition, there is supplementary documentation about this code.

Good readability of code means, for example:

• Using meaningful and standardised names for variables (also for functions and classes),
• Structuring code according to the possibilities of the programming language used (for instance in functions and classes),
• Formatting code consistently (such as indentations),
• Write comments in the code about what it does and what a variable (or a function or class) is used for, for example. When formulating the code, assume that the reader is familiar with the basics of the programming language. If your code is linked to an academic publication, it is recommended that, for example, the sequence of data analysis steps described in a publication can be identified by corresponding comments in the code.

The options for structuring code essentially depend on the programming language used, where functions and classes are common terms. You can find an overview of the possibilities of numerous programming languages at W3 Schools.

How to write and organise code is usually set out in a style guide for each programming language, examples of which can be found at The Turing Way.

You can also store basic information about the code (reference to a project / sponsor, authors, content description for functionality, software and package dependencies and so on) as a comment in the source code in a central location or in a separate README file. If you use a code repository such as GitHub, there are corresponding fields for metadata for a lot of information.

Tip for documentation: “Ten simple rules for documenting scientific software“