2. Documentation

Guido van Rossum is rather important in the history of Python! One of the points he makes is that you may write code once, but many other people (including yourself) will have to read it in the future, to refactor, debug, modify, audit, etc. The exact quote is “Code is more often read than written”.

We often hear the terms comments and documentation used interchangeably. As a start, let us differentiate between them.

Comments are how you describe your code to other developers or for your later self.

Documentation describes the use and functionality of the code.

Projects will have a dedicated repo, with a readme.md in the root explaining and summarizing the project, and a \docs folder with detailed documentation. This will be dealt with later in the notes, under Project Anatomy.

I wish I could say there was universal agreement on how to document code, but it is an area of debate and difference, even when using the PEPs.

Before you begin. create a directory to keep example files in and you are ready to code.

This could be on your OneDrive, in these examples, I am using OneDrive\Python\Exercises_02

I am using the command line interpreter (CLI) or interactive shell for some of these notes. This lets me run simple code and interpret the output immediately.

I also use Notepad ++ for other exercises. Use the editor of your choice.