註解

1、註解

#1.1、區(qū)塊註解

「#」號(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)鍵部分(或比較複雜的地方),能寫(xiě)註解的要盡量寫(xiě)註解

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

app = create_app(name, options)
# =====================================
# 請(qǐng)勿在此處添加 get post等app路由行為 !!!
# =====================================
if __name__ == '__main__':
    app.run()

#2、文件註解（ Docstring）

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

文件註解以""" 開(kāi)頭和結(jié)尾, 首行不換行, 如有多行, 末行必需換行, 以下是Google的docstring風(fēng)格範(fàn)例

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

不要在文件註解複製函數(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ō)明採(cǎi)用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ě)文檔註釋