From 324c8e67604b0afa2dabd74b4173926670fd1e29 Mon Sep 17 00:00:00 2001 From: dshendler Date: Thu, 29 Oct 2015 00:05:46 -0500 Subject: [PATCH] tried to clarify the commenting sections --- docs/writing/documentation.rst | 35 ++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 58a3107c4..9fed0c2f1 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -93,26 +93,14 @@ Reference`_ should help you familiarize yourself with its syntax. Code Documentation Advice ------------------------- -Comments clarify the code and they are added with purpose of making the -code easier to understand. In Python, comments begin with a hash -(number sign) (``#``). - -.. _docstring-ref: - -In Python, *docstrings* describe modules, classes, and functions: - -.. code-block:: python - - def square_and_rooter(x): - """Returns the square root of self times self.""" - ... - -In general, follow the comment section of :pep:`8#comments` (the "Python Style -Guide"). Commenting Sections of Code ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Comments clarify the code and they are added with purpose of making the +code easier to understand. In Python, comments begin with a hash (also known +as number or pound sign) (''#''). + *Do not use triple-quote strings to comment code*. This is not a good practice, because line-oriented command-line tools such as grep will not be aware that the commented code is inactive. It is better to add @@ -120,6 +108,10 @@ hashes at the proper indentation level for every commented line. Your editor probably has the ability to do this easily, and it is worth learning the comment/uncomment toggle. +In general, follow the comment section of :pep:`8#comments` (the "Python Style +Guide"). + + Docstrings and Magic ~~~~~~~~~~~~~~~~~~~~ @@ -127,6 +119,17 @@ Some tools use docstrings to embed more-than-documentation behavior, such as unit test logic. Those can be nice, but you won't ever go wrong with vanilla "here's what this does." +.. _docstring-ref: + +In Python, *docstrings* describe modules, classes, and functions: + +.. code-block:: python + + def square_and_rooter(x): + """Returns the square root of self times self.""" + ... + + Docstrings versus Block comments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~