Menu
In python we designate internal function/ private methonds with an underscore at the beginning. Should these functions be documented with docstrings(is it required?)? (the formal documentation i mean, not the one helping the code-reader to understand the code) What is common practice for this?
211
Every function you create ought to have a docstring. They're in triple-quoted strings and allow for multi-line text.
Python documentation strings (or docstrings) provide a convenient way of associating documentation with Python modules, functions, classes, and methods. It's specified in source code that is used, like a comment, to document a specific segment of code.
It is an essential part that documenting your code is going to serve well enough for writing clean code and well-written programs. Docstrings help you understand the capabilities of a module or a function.
Module docstrings are placed at the top of the file even before any imports. Module docstrings should include the following: A brief description of the module and its purpose. A list of any classes, exception, functions, and any other objects exported by the module.
Lo, I quote from PEP 8, the wise words of which should be considered law. Upon this very topic, PEP 8 saith:
- Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the "def" line.
157
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
