PEP 8: docstring question

kesha1225 · February 12, 2024, 4:37pm

python/peps/blob/53c3d1a703e4f3208c59699f9ad7e313919327cf/peps/pep-0008.rst?plain=1#L868


      
             :class: good
          
             x = x + 1                 # Compensate for border
          
          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.
          
          - :pep:`257` describes good docstring conventions.  Note that most
            importantly, the ``"""`` that ends a multiline docstring should be
            on a line by itself:
          
            .. code-block::
               :class: good

Does this mean that each of my functions must have a docstring, even if it is a single line or the only one in the file? Or if this function is the only one written exclusively for the programming competitions?

pf_moore · February 12, 2024, 4:42pm

No.

PEP 8 is only guidelines, not rules. Use your judgement.
PEP 8 is technically only the style guide for code writtent for the standard library. It’s your choice whether you follow it in your own code.

kesha1225 · February 12, 2024, 4:46pm

Thank you for your assistance!

smontanaro · February 12, 2024, 5:14pm

Though some tools (black comes to mind, others in their default configuration) treat PEP-8 as if it was engraved on tablets handed down from on high. YMMV…

jamestwebber · February 12, 2024, 5:14pm

I don’t think black is even compliant with pep 8?

smontanaro · February 12, 2024, 5:15pm

That could be. I used it once, then uninstalled it.

Topic		Replies	Views
PEP 727: Documentation Metadata in Typing PEPs typing	172	15733	February 24, 2024
Revisiting attribute docstrings Ideas documentation	29	3167	December 13, 2023
PEP-8: clarify if multiline argument list with a closing `)` on a separate line is acceptable PEPs	23	36215	November 1, 2020
Docstrings for new type aliases as defined in PEP 695 Typing documentation	5	1562	December 6, 2023
Function Docstring Generator Python Help	3	2553	April 25, 2021

PEP 8: docstring question

Related Topics