Comment

Comments

1, Comments

1.1,Block comments

Leave one space after the "#" sign, and separate paragraphs with blank lines (the "#" sign is also required)

# 块注释
# 块注释
#
# 块注释
# 块注释

1.2. Line comments

At least Use two spaces to separate statements, and be careful not to use meaningless comments

# 正确的写法
x = x + 1  # 边框加粗一个像素
# 不推荐的写法(无意义的注释)
x = x + 1 # x加1

1.3. It is recommended that

be used in key parts of the code (or more complex places), Those who can write comments should try to write comments

The more important comment sections are separated by multiple equal signs, which can be more eye-catching and highlight the importance

app = create_app(name, options)
# =====================================
# 请勿在此处添加 get post等app路由行为 !!!
# =====================================
if __name__ == '__main__':
    app.run()

2. Document comments ( Docstring)

Docstring as a document generally appears in the header of modules, functions and classes, so that the document can be obtained through the __doc__ object of the object in python. Editors and IDEs can also Automatic prompts are given based on Docstring.

Document comments start and end with """, and the first line does not break. If there are multiple lines, the last line must break. The following is an example of Google's docstring style

# -*- coding: utf-8 -*-
"""Example docstrings.
This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.
Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::
        $ python example_google.py
Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
"""

Do not copy the function definition prototype in the document comments, but describe its specific content in detail, explain the specific parameters and return values, etc.

#  不推荐的写法(不要写函数原型等废话)
def function(a, b):
    """function(a, b) -> list"""
    ... ...
#  正确的写法
def function(a, b):
    """计算并返回a到b范围内数据的平均值"""
    ... ...

The description of function parameters, return values, etc. adopts the numpy standard, as shown below

def func(arg1, arg2):
    """在这里写函数的一句话总结(如: 计算平均值).
    这里是具体描述.
    参数
    ----------
    arg1 : int
        arg1的具体描述
    arg2 : int
        arg2的具体描述
    返回值
    -------
    int
        返回值的具体描述
    参看
    --------
    otherfunc : 其它关联函数等...
    示例
    --------
    示例使用doctest格式, 在`>>>`后的代码可以被文档测试工具作为测试用例自动运行
    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """

Document comments are not limited to Chinese and English, but do not mix Chinese and English

Document comments are not as long as possible, usually one or two sentences can explain the situation clearly

For modules, public classes, and public methods, those who can write documentation comments should try to write documentation comments