Notes Python (Python Comments) Detailed usage

@

Comment 1 Python Overview

Note (Comments) is used to explain the ideas or tips, the role and function of some other code the developer (user) may be added anywhere in the code. Python interpreter (Python Interpreter) in the implementation of the program (the code) will ignore the comment section, without any treatment, that is, the comment section will not be executed Python interpreter.

Add the appropriate amount of comments in the code is very important, notes typically accounts for about 1/3 of the source code.

Python supports two types of comments: single-line and multi-line comments.

Role 2 Python comments

2.1 debugging code

Debug (the Debug) process program, one-line comments can be quickly annotated to some temporary codes, to reduce the error range, to improve the efficiency of program debugging purposes.

To do the following:
In the case of uncertain what specific lines of code errors, we can put that potentially problematic code comments up, and then run the program observation. If the program can be executed properly, it shows that the error is caused by this code; on the contrary, if the same error still occurs, it shows that the error was not caused by this code.

2.2 improve the readability of the program

Notes the biggest role is to improve the readability, no annotation program is hard to understand, saying that the bible is not excessive.
Even more, write your own code, over a period of time, will forget their own ideas or purposes.

3 Python single-line comments

3.1 Python single-line comments Overview

Python is using the # #symbol as a single-line comments, its syntax is as follows:

# 添加的注释内容

The above description of the syntax:

• #As a single-line comment symbol.
• From the pound sign #to start until all the content until the end of the line is a comment. Python interpreter encounters #when it ignores the entire line behind that #line after the contents belong to the comments section.

3.2 The single line of code is a single row Note Note

For one line Note Note single line of code will usually comment on the right side of the code, and the code is spaced between two spaces, as follows:

print("码农阿杰")  # 输出笔者的微信公众号名称
print('https://www.cnblogs.com/manongajie/')  # 输出笔者的博客园博客地址
print('https://blog.csdn.net/manongajie/')  # 输出笔者的CSDN博客地址

3.3 Note Note multiline single line of code

When the single-line comment comment lines of code in the code comments generally on line, as follows:

# 使用 print() 内置函数输出字符串
print("微信公众号：码农阿杰")
print("博客园博客地址 https://www.cnblogs.com/manongajie/")
print("CSDN 博客地址 https://blog.csdn.net/manongajie/")

# 使用 print() 内置函数输出数字
print(520)
print(521)
print(1314)

3.4 Single-line comments Notes

3.4.1 Single-line comments symbol as part of the string is present

When a single line comment symbol #time appearing as part of the string, then it can not be labeled as a single-line comment, but should be as part of a string (character string), as follows:

print('# 微信公众号：码农阿杰')
print("# 博客园博客地址 https://www.cnblogs.com/manongajie/""")
print("# CSDN 博客地址 https://blog.csdn.net/manongajie/")

operation result:

# 微信公众号：码农阿杰
# 博客园博客地址 https://www.cnblogs.com/manongajie/
# CSDN 博客地址 https://blog.csdn.net/manongajie/

Above code shows:

• Python is not the pound sign #as a single-line comment tag, but it as part of the string.

4 Python multi-line comments

Overview 4.1 Python multi-line comments

Refers to a multi-line comments disposable comment lines of code in the program, it may be one line of code.

Python are supported in three consecutive single quotes '''were used as the beginning and end of the comment, or three consecutive double quotes """were used as the beginning and end of the comment, the comment disposable single row or multiple rows of content.

Multi-line comments are usually used to Python functions, classes, modules, etc. add functionality, version, and author and other descriptive information.

4.2 Notes three consecutive single quotes

Three consecutive single quotes annotation content following format:

'''
使用三个连续的单引号分别作为注释的开头和结尾
可以一次性注释多行内容或单行内容
'''

4.3 Notes three successive quotation

"""
使用三个连续的双引号分别作为注释的开头和结尾
可以一次性注释多行内容或单行内容
"""

More than 4.4-line comments can also provide documentation for the function

May Python by help()or built-in functions __doc__attribute view the documentation for a function, as shown in the following code:

# 查看 print() 内置函数的说明文档
print('--- 用 help()内置函数查看说明文档 ---')
help(print)
print('--- 用 __doc__ 属性查看说明文档 ---')
print(print.__doc__)

operation result:

--- 用 help()内置函数查看说明文档 ---
Help on built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    
    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

--- 用 __doc__ 属性查看说明文档 ---
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file:  a file-like object (stream); defaults to the current sys.stdout.
sep:   string inserted between values, default a space.
end:   string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.

In fact, the documentation function is essentially a string (multi-line comments with the same symbol), require programmers to write their own, but as an illustration is different placement of documents, string, documentation function normally located inside function the foremost of all the code.

It is a function of how the documentation set? As follows:

# 定义一个比较数字大小的函数
def num_max(num1, num2):
    """
    比较两个数字的大小
    :param num1:形参1，数字1
    :param num2:形参2，数字2
    :return:大的数字，max_num = num1 if num1 > num2 else num2
    """
    max_num = num1 if num1 > num2 else num2
    return max_num


result = num_max(1, 2)
print(result)
print('--- 用 help() 内置函数查看 num_max() 的说明文档 ---')
help(num_max)
print('--- 用 __doc__ 属性查看 num_max() 的说明文档 ---')
print(num_max.__doc__)

operation result:

2
--- 用 help() 内置函数查看 num_max() 的说明文档 ---
Help on function num_max in module __main__:

num_max(num1, num2)
    比较两个数字的大小
    :param num1:形参1，数字1
    :param num2:形参2，数字2
    :return:大的数字，max_num = num1 if num1 > num2 else num2

--- 用 __doc__ 属性查看 num_max() 的说明文档 ---

    比较两个数字的大小
    :param num1:形参1，数字1
    :param num2:形参2，数字2
    :return:大的数字，max_num = num1 if num1 > num2 else num2
    

More than 4.5-line comments Notes

4.5.1 Multi-line comments do not support nested

Python does not support nested multi-line comment, an error written as follows:

'''
外层注释
    '''
    内层注释
    '''
'''

4.5.2 Multi-line comments symbol '''or """a string tag

Multi-line comments symbols '''or """may begin and end with a string tag.

When a plurality of the Python line comments appear as part of a string of symbols, then they can not be used as multi-line comment tag, but should be seen as part of the string, as follows:

str_info1 = '''微信公众号：码农阿杰'''
str_info2 = """博客园博客地址 https://www.cnblogs.com/manongajie/"""
str_info3 = "CSDN 博客地址 https://blog.csdn.net/manongajie/"

print(str_info1)
print(str_info2)
print(str_info3)

operation result:

微信公众号：码农阿杰
博客园博客地址 https://www.cnblogs.com/manongajie/
CSDN 博客地址 https://blog.csdn.net/manongajie/

Above code shows:

• Python is not the three quotes here as a multi-line comments, but they are seen as the start and end markers strings.

5 Other articles address

5.1 micro-channel public number: agriculture Adger code

5.2 CSDN blog

6 References

6.1 Python 3.8.2 documentation