Are docstrings for internal functions (python) necessary?

python documentation standards pep8
0xc0de picture 0xc0de · Oct 7, 2011 · Viewed 7.6k times · Source

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?

Answer

Chris Morgan picture Chris Morgan · Oct 7, 2011

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.

Related questions

Is there a way to create multiline comments in Python?

I have recently started studying Python, but I couldn't find how to implement multi-line comments. Most languages have block comment symbols like /* */ I tried this in Python, but it throws an error, so this probably is not the correct way. …

Read More
What is the standard Python docstring format?

I have seen a few different styles of writing docstrings in Python, is there an official or "agreed-upon" style?

Read More
How do I create documentation with Pydoc?

I'm trying to create a document out of my module. I used pydoc from the command-line in Windows 7 using Python 3.2.3: python "<path_to_pydoc_>\pydoc.py" -w myModule This led to my shell being filled with text, one …

Read More