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
Advertisements

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s

%d bloggers like this: