Python Docstrings 101

Good code is self-documenting code.

That’s why I’m getting into the habit of using Python Docstrings.

Here is a summary:

  • Where
    • First statement in module, function, class, or method (the “thing”) definition
  • Why
    • Becomes the __doc__ special attribute of the “thing” it’s documenting
  • What
    • Don’t document the “thing’s” name or “signature”; you can get that with introspection.
    • Do document the return value; you can’t get that with introspection.
  • How
    • Triple double quotes (can be r (raw) or u (unicode))
    • Prescription > description. Method’s effect, not only its result.
  • More

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: