Idiomatic file level comments in Python?

Question

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?

Always use the first, since that will actually populate __doc__, the other one is just a comment. — MaxNoe
– MaxNoe, Commented May 22, 2021 at 12:21

MaxNoe · Accepted Answer · 2021-05-22 12:23:08Z

6

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.

answered May 22, 2021 at 12:23

MaxNoe

15.1k3 gold badges44 silver badges52 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

Idiomatic file level comments in Python?

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related