Conventions are Arbitrary, So Use This One

Despite the title, my intention is not to start a flame war. I want to discuss docstring conventions in Python, but just as a case study for conventions in general.

I suggested a while ago in my team at work that we should probably agree on docstring conventions. Each of us had different conventions in mind, me included. Instead of just, you know, thinking for myself, I Googled “python docstring conventions” and lo and behold - the first result was PEP 257:

• Triple quotes are used even though the string fits on one line. This makes it easy to later expand it.
• The closing quotes are on the same line as the opening quotes. This looks better for one-liners.
• There’s no blank line either before or after the docstring.
• The docstring is a phrase ending in a period. It prescribes the function or method’s effect as a command (“Do this”, “Return that”), not as a description; e.g. don’t write “Returns the pathname …”.
• The one-line docstring should NOT be a “signature” reiterating the function/method parameters (which can be obtained by introspection).
• […]

And it goes on. Now, you may agree with some of these items and disagree with other (personally - the “phrase as a command” I love; the “put a blank line before the ending quotes”, not so much), but I think the value of this document is that it simply exists and is agreed upon. Caring about how many spaces to put before a curly brace is a phase. It’s one of the steps of teaching yourself how to program:

• Get involved in a language standardization effort. It could be the ANSI C++ committee, or it could be deciding if your local coding style will have 2 or 4 space indentation levels. Either way, you learn about what other people like in a language, how deeply they feel so, and perhaps even a little about why they feel so.
• Have the good sense to get off the language standardization effort as quickly as possible.

However, caring about which standardization to use is wholly different from caring about whether you’re complying with any. Standards are arbitrary, yes, but they’re important. I think PEP 257 is great. Not because they get the spacing right, but because it’s important to have an agreed upon document (signed by the BDFL - a bonus) that does just this. So when I review other people’s code, I correct them and I refer them to this PEP. If they complain I say “I don’t care where we put our spaces, but we should be consistent. Somebody already did the work of putting a document together, so why not use it?”.

Similar Posts

• Python Attribute Access and the Descriptor Protocol
• File Parts: Cheat Sheet
• Python Idioms: Multiline Strings
• Python Entry Points Explained
• Cleaning Up in a Python Generator Can Be Dangerous
• Write Explicit Tests