Idiomatic file level comments in Python?

user_4642943 0
Viewed 55

When I need to write extensive comments about functions, I use docstrings. However, I'm not sure what the equivalent for file level comments is in Python, and whether it differs for modules vs scripts.

Is it common to use this style?

"""
file.py: module for X
Detailed information...
"""

import x

def foo(bar):
  return 42

Or perhaps this?

# file.py: module for X
# More info...

import x
# ...

Any thoughts?

python
1 Answers

Always use a string, since that will actually populate the __doc__ variable of the current file / module.

Compare this:

'''Hello World'''
print(__doc__)

to

# Hello World
print(__doc__)

Consider this is in a module foo.py and compare the output off:

>>> import foo
>>> help(foo)

You also do not need to add the "file: ..." part, since python displays that automatically.

user_38386910
Related