1、注釋

1.1、塊注釋

“#”號(hào)后空一格，段落件用空行分開(kāi)（同樣需要“#”號(hào)）

# 塊注釋
# 塊注釋
#
# 塊注釋
# 塊注釋

1.2、行注釋

至少使用兩個(gè)空格和語(yǔ)句分開(kāi)，注意不要使用無(wú)意義的注釋

# 正確的寫(xiě)法
x = x + 1  # 邊框加粗一個(gè)像素

# 不推薦的寫(xiě)法(無(wú)意義的注釋)
x = x + 1 # x加1

1.3、建議

• 在代碼的關(guān)鍵部分(或比較復(fù)雜的地方), 能寫(xiě)注釋的要盡量寫(xiě)注釋

• 比較重要的注釋段, 使用多個(gè)等號(hào)隔開(kāi), 可以更加醒目, 突出重要性

app = create_app(name, options)

# =====================================
# 請(qǐng)勿在此處添加 get post等app路由行為 !!!
# =====================================

if __name__ == '__main__':
    app.run()

2、文檔注釋?zhuān)―ocstring）

作為文檔的Docstring一般出現(xiàn)在模塊頭部、函數(shù)和類(lèi)的頭部，這樣在python中可以通過(guò)對(duì)象的__doc__對(duì)象獲取文檔. 編輯器和IDE也可以根據(jù)Docstring給出自動(dòng)提示.

• 文檔注釋以 """ 開(kāi)頭和結(jié)尾, 首行不換行, 如有多行, 末行必需換行, 以下是Google的docstring風(fēng)格示例

# -*- 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.
"""

• 不要在文檔注釋復(fù)制函數(shù)定義原型, 而是具體描述其具體內(nèi)容, 解釋具體參數(shù)和返回值等

#  不推薦的寫(xiě)法(不要寫(xiě)函數(shù)原型等廢話(huà))
def function(a, b):
    """function(a, b) -> list"""
    ... ...

#  正確的寫(xiě)法
def function(a, b):
    """計(jì)算并返回a到b范圍內(nèi)數(shù)據(jù)的平均值"""
    ... ...

• 對(duì)函數(shù)參數(shù)、返回值等的說(shuō)明采用numpy標(biāo)準(zhǔn), 如下所示

def func(arg1, arg2):
    """在這里寫(xiě)函數(shù)的一句話(huà)總結(jié)(如: 計(jì)算平均值).

    這里是具體描述.

    參數(shù)
    ----------
    arg1 : int
        arg1的具體描述
    arg2 : int
        arg2的具體描述

    返回值
    -------
    int
        返回值的具體描述

    參看
    --------
    otherfunc : 其它關(guān)聯(lián)函數(shù)等...

    示例
    --------
    示例使用doctest格式, 在`>>>`后的代碼可以被文檔測(cè)試工具作為測(cè)試用例自動(dòng)運(yùn)行

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """

• 文檔注釋不限于中英文, 但不要中英文混用

• 文檔注釋不是越長(zhǎng)越好, 通常一兩句話(huà)能把情況說(shuō)清楚即可

• 模塊、公有類(lèi)、公有方法, 能寫(xiě)文檔注釋的, 應(yīng)該盡量寫(xiě)文檔注釋