Parsing Python code comment specification code

##1. Introduction to code comments

Comments are explanations and explanations of the code, and their purpose is to make it easier for people to understand the code.
• Comments are when the programmer writes an explanation or hint for a statement, program segment, function, etc., which can improve the readability of the program code.
• In codes with processing logic, the amount of effective comments in the source program must be more than 20%.

Relevant learning recommendations:

python video tutorial

2. Code comment classification

Line comment: The line after the symbol will not be compiled (displayed)

Block comment: The part in the middle of the block comment symbol will not be compiled Compile

3. Basics of python code comments

# is used in Python to represent single-line comments. Single-line comments can be placed as a separate line above the line of code being commented, or after a statement or expression. The following example:

name = 'xiaohong' # Single line comment

# Single line comment

name = 'xiaohong'

Use three single quotes or three double quotes in Python to indicate multi-line comments. Used when there are too many comments to write, as in the following example:

'''

This is a multi-line comment using three single quotes
'''

"""

This is a multi-line comment using three double quotes
"""

4. Introduction and use of DocStrings

4.1 Introduction to DocStrings

Document string

is an important tool for interpreting documentation programs. Help your program documentation to be simpler and easier to understand

4.2 Using DocStrings in Python

Use a pair of three single quotes''' or a pair of three in the first line of the function body Double quotes """ to define the docstring. You can use doc (note the double underscore) to call the docstring attribute in the function.

Writing example is as follows:

def add(num1,num2):
  """ 完成传入的两个数之和

  :param num1: 加数1
  :param num2: 加数2
  :return: 和
  """
  return num1 + num2

print( add.__doc__ )

Remarks: DocStrings Document string usage convention: Its first line briefly describes the function function, the second line is blank, and the third line is a specific description of the function.

5. Common writing styles of DocStrings

5.1 reST style

This is a popular style now, reST style, the royal format of Sphinx, which is relatively compact.

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

5.2 Google style

"""
This is a groups style docs.

Parameters:
 param1 - this is the first param
 param2 - this is a second param

Returns:
 This is a description of what is returned

Raises:
 KeyError - raises an exception
"""

5.3 Numpydoc (Numpy style)

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
 the 1st param name `first`
second :
 the 2nd param
third : {'value', 'other'}, optional
 the 3rd param, by default 'value'

Returns
-------
string
 a value in a string

Raises
------
KeyError
 when a key error
OtherError
 when an other error
"""

6. Some annotation experience

The more comments, the better. For code that is clear at a glance, there is no need to add comments.
• For complex operations, corresponding comments should be written before the operation starts.
• For code that is not clear at a glance , comments should be added after the code.
• Never describe the code. Generally, people who read the code know the syntax of Python, but they just don’t know what the code is doing

Related learning Recommended:

Programming Video

The above is the detailed content of Parsing Python code comment specification code. For more information, please follow other related articles on the PHP Chinese website!