Documentation

It is important to document how software works, because it allows people to understand how it works a lot faster than by trying to make sense of the source code. We’re not only talking about other people here, by the way. When you get back to working on some software project after a break of several months, you will also thank yourself for having written good documentation.

Software can be provided with many different flavors of documentation, including…

API reference: Summarizes what individual data types are meant to store, what functions take as input and emit as output, what are the error conditions…
Tutorials/Examples: Introduces a new user to the software, what it does, and how it’s used in some concrete, hopefully common scenarios.
Architecture/Design overview: In larger software, explains how the various sub-parts fit together and why they were designed that way.
Contribution guide: In open-source projects, tells newcomers about how to best submit new contributions to the software.
Data management plan: In applications that are meant to store user data for extended periods of time, explains how data gets there, how long it’s kept in the system, how it’s protected from system failures…

Documentation is not even necessarily a written document that’s separate from the source code. Some aspects of the source code, such as the name and type of code entities, can also provide basic documentation to the reader of the code. For example, compare the following two functions:

# Would you rather use this function?
def do_stuff(x, y):
    return x[y]


# ...or this function?
def get_phone_number(
    phone_book: dict[Name, PhoneNumber],
    full_name: Name
) -> PhoneNumber:
    return phone_book[full_name]

// Would you rather use this function?
auto do_stuff(auto&& x, auto&& y) {
    return x[y];
}


// ...or this function?
PhoneNumber get_phone_number(const std::map<Name, PhoneNumber>& phone_book,
                             const Name& full_name) {
    return phone_book[full_name];
}

Even though do_stuff and get_phone_number can be used to do the same thing, you will hopefully agree that get_phone_number is a lot easier to understand in its because it’s more specific about what it does. There is a more general lesson to be learned here: your code should only be as generic as it needs to be for the task at hand, because specific programs are easier to understand, document, test and maintain than generic ones. Please resist the temptation to write code which solves problems that you do not have!

In this practical, we will cover the two most common forms of documentation, namely API documentation and tutorials. API documentation tools are language-specific so you will need to pick which language you want to study here:

Robust Programming

Documentation