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? If the code is clear enough without the comment, it’s better to remove it.
Comments & Docstrings
Video
Slides
Exercise
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? If the code is clear enough without the comment, it’s better to remove it.