I know what's the standard way to document functions, classes and modules, but how do I document packages - do I put a docstring in __init__.py, or something else?
Add a comment
|
3 Answers
Yes, just like for a function or class comment, the first item in the __init__.py file should be a comment string:
"""
This is the xyz package.
"""
Now if you import the package, and use help(package), you will see your docstring. See more here: http://www.python.org/dev/peps/pep-0257/
Comments
See PEP257
A package may be documented in the module docstring of the __ init __.py file in the package directory.
Comments
Documenting is a good idea, so long as you don't document something obvious in your code
Try to understand that most people reading your source will understand python, so commenting or documenting lines like this is pointless:
a = 1 #this assigns 1 to a
But commenting or documenting a rather complicated function or class is a good idea.
General rule of thumb: Imagine the next person to work on your code is a Axe wielding maniac and they know where you live.
That way you will always leave "helpful" comments/doc's
1 Comment
OrOrg
Ironic. The comment about helpful comments was not helpful.