深入理解document & comment in Python

• Overview

  Code is more often read than written — Guido Van Rossum

  In general, commenting is describing your code to developer(code tells you how, Comments tell you why);

  Documentinig code is describing its use and functionality to your users.

• Commenting Code

• Basics of Commenting Code

  Comments are created in Python using the pound sign (#);

  According to PEP8, comments should have a maximum length of 72 characters.

  Following four essential rules suggested by Jeff Atwood:

  1. Keep comments as close to the code being described as possible;
  2. Don’t use complex formatting;
  3. Don’t include redundant information;
  4. Design your code to comment itself;

• Commenting Code via Type Hinting

• Documenting Your Code Using Docstrings

  The strategic placement of the string literal direclty below the object will automatically set the __doc__ value.

  Docstring conventions are described within PEP257.

  The docstring should use the triple-double quote (""") string format.

  Multi-lined docstrings are used to further elaborate on the object beyond the summary. All multi-lined docstrings have the following parts:

  • A one-line summary line
  • A blank line proceeding the summary
  • Any further elaboration for the docstr