Parsing Python code comment specification code-Python Tutorial-php.cn

Parsing Python code comment specification code

coldplay.xixi

Release： 2020-08-15 17:18:41

forward

3789 people have browsed it

##1. Introduction to code comments

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__ )

Copy after login

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
"""

Copy after login

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
"""

Copy after login

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 : {&#39;value&#39;, &#39;other&#39;}, optional
 the 3rd param, by default &#39;value&#39;

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

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

Copy after login

6. Some annotation experience

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!