Slides on Documentation (for reference)
The following topics are covered:
- commenting code and functions (docstrings)
- writing a README file
Time for some documentation around your code! As usual, we have short videos and accompanying exercises. Watch the video, then apply the exercises to your own project. Use the slides linked above for reference, and be sure to ask for help when you need it!
Video: Comments and docstrings
- Add a docstring to a function, preferably the last function you worked on (so it's fresh in your memory). Keep in mind: what does my user need to know when they are working with this function?
- Grab a limited chunk of code to work on, and look at the existing comments. Can you replace a 'how' comment with a 'why' comment? Think: what is the purpose of this code? Rather than: this is how this code works.
- Are there elements in your chunk that are currently without comments that would benefit from clarification? Try to comment on the thought behind the code rather than simply translating its process in English.
- Can you delete superfluous comments or zombie code?
Edit your README file. Take your time. This is important!
Make sure to include the following information:
- What does your project do?
- How does the user access your project? (E.g. download, or clone with
git clone...) - How does the user call the main script(s) that should be executed?
- And perhaps any other elements you are inspired to add (check out the examples!)
Do you want to truly understand the importance of decent installation information? Read this experience by Elisabeth Bik, trying to install image forensics software. Look at the README of the software, and see what you can learn.
NB: We will have another chance to take a look at dependencies and prerequisites, but if you have opportunity to add these here: please do!