Docstring explains how to use code, and are for the users of your code. Use of docstrings:
- Explain the purpose of the function even if it seems obvious to you, because it might not be obvious to someone else later on.
- Describe the parameters expected, the return values, and any exceptions raised.
- If the method is tightly coupled with a single caller, make some mention of the caller (though be careful as the caller might change later).
Comments explain why, and are for the maintainers of your code. Examples inlcude notes to yourself, like:
- # !!! BUG: …
- # !!! FIX: This is a hack
- # ??? Why is this here?
NOTE: False comments & docstrings are worse than none at all. So keep them up to date! When you make changes, make sure the comments & docstrings are consistent with the code, and don’t contradict it.