1

Default docstring from PyCharm automatically creates template with Args: and Returns: sections. However I have observed that this prompts people to say obvious things, frequently just stating the variable name without underscores (if name was chosen well).

My first external source was the source code of mypy, a project where GvR is one of the developers (therefore I expect it to be in line with best practices). Documentation there is plain english stating the purpose and further details, but everything about args and return is only in the (typed) method signature and var names.

However, PEP257 states: The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.

Result is currently that I am trying to use best judgement on where we can make useful comments including Args: Returns: and where it is redundant, but this makes it look very diverse and unpredictable.

Background: I am trying to establish best practices for comments in a small python project (5 people).

1

Writing good documentation is an art unto itself. Repeating yourself (e.g., repeating the variable name without underscores) is valueless; e.g., ++i; // increment i. If you're just repeating variable names without underscores, then you're not adding to anyone's understanding of the code.

I think it's always important to document what exceptions your methods throw. Return values aren't always as obvious as the original programmer thinks they are, so that's usually useful to document as well. (Again, if your method is get_foo(), saying "returns a foo" doesn't add anything.)

One thing to point out about that mypy example, the authors are using type hints which replaces a lot of what would be included in a docstring:

def warn(self, msg: str, context: Context, file: Optional[str] = None, origin: Optional[Context] = None)

Just from this, I know exactly what this method expects. Without it:

def warn(self, msg, context, file = None, origin = None)

I know a lot less.

  • So you would agree that type hints plus good var names make Args: section redundant? – ikamen Mar 6 at 13:46
  • Sometimes. I had a variable today that was something like output_directory but because other components were generating data into temp locations, it was clearer to me to add a comment saying something like "final directory where results are stored". This was code I originally wrote less than 6 months ago, but coming back to tweak it, I had to study the code to remember which output directory that variable was. That's why I wrote the comment. To be painfully clear: Sometimes, what is obvious/clear to you isn't to others or your future self. – Matthew Mar 6 at 20:29
2

I can not give you a definite answer, since such documentation also is sort of work and as such should be done, if useful. Generally speaking, only useful functionality should be exposed to the user and the application should be easy to use and understand.

Arguments Even obvious things can be exported for fast lookup. This is usually helpful for long and tedious methods. Optional parameters can be easily integrated by default parameters.
Return values With python it can be a pain to look up return values by inspecting objects (without source code), so when the source code is not at hand this should be done.
Side effects This is a quite vague term, but at least thread-safety support should be annotated in mixed applications cases (or explicitely). Default however is not thread-safe.
Exceptions Enforcing programmer/user input should be definitely documented, since this will cause crashing behavior.

In a small project, and as such internal project, for given knowledge and (hopefully) code, it does not make too much sense to comment everything. Concentrate on data structures and use cases for functions.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.