Is it a good practice to use triple quotes to create "docstrings" in non-standard contexts?

Question

I am looking at someone's code which has this kind of "docstrings" all over the place:

SLEEP_TIME_ON_FAILURE = 5
"""Time to keep the connection open in case of failure."""

SOCKET_TIMEOUT = 15
"""Socket timeout for inherited socket."""

...

As per the Python documentation, docstrings are applicable only in the context of the beginning of a module, class, or a method.

What is the implication of the above non-standard practice? Why does Python allow this? Doesn't this have performance impact?

Answer 1

As far as Python is concerned, these aren't docstrings. They're just string literals used as expression statements. You can do that - you can use any valid Python expression as its own statement. Python doesn't care whether the expression actually does anything. For a string on its own line, the only performance impact is a very small amount of extra work at bytecode compilation time; there's no impact at runtime, since these strings get optimized out.

Some documentation generators do look at these strings. For example, the very common Sphinx autodoc extension will parse these strings to document whatever is directly above them. Check whether you're using anything like that before you change the code.

Answer 2

In python, the """ is syntax for a multi-line string.

s1 = """This is a multi-line string."""
s2 = """This is also a multi-line
string that stretches 
across multiple lines"""

If these strings are not stored into a variable, then they are immediately garbage collected, and are essentially ignored, but they still use some overhead. On the other hand, comments using # are actually completely ignored by the interpreter.

The only exception to this rule is when this docstring comes immediately after a function or class definition, or on top of a module. In that case, it is stored in the special variable __doc__.

According to PEP8,

Documentation Strings Conventions for writing good documentation strings (a.k.a. "docstrings") are immortalized in PEP 257.

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.

Answer 3

In those cases you should use a in-line comment, which the PEP8 style guide clearly defines https://www.python.org/dev/peps/pep-0008/#comments, e.g.:

SLEEP_TIME_ON_FAILURE = 5  # Time to keep the connection open in case of failure

SOCKET_TIMEOUT = 15  # Socket timeout for inherited socket