Code documentation

Prerequisites

No previous knowledge is needed to start reading this chapter. This chapter aims to provide guidance to projects with different types of code and thus different needs (from small scripts to large libraries), so at some points it may require some knowledge of writing code.

Summary

A famous quote be Harold Abelson says that “Programs must be written for people to read, and only incidentally for machines to execute.” This refers to the fact that code should be written in a way that it can be understood by people other than the author (and even the author in the future). And this is not limited to the code itself being well written, but also (and perhaps more importantly) for the code to be clearly documented.

Documentation is the written text that acompanies the code and explains different aspects of it: what it does, how it works, how it is structured, and any other relevant information. Depending on the complexity of the code, it may be suitable to have different types of documentation aimed at different audiences for example, the users of the software, or other developers.

It is important to emphasise that not all projects need extensive documentation; sometimes a basic README and a few comments in the code are sufficient for your audience. As the author of your code, it is up to you to decide the level of documentation that you need.

In this chapter we cover different types of documentation, from the very basics of how to document your code itself up to how to document your software project. The other resources section includes multiple links to external resources that can help you further.