註解
註解
1、註解
#1.1、區塊註解
「#」號後空一格，段落件用空白行分開（同樣需要「#」號）
# 块注释 # 块注释 # # 块注释 # 块注释
1.2、行註解
至少使用兩個空格和語句分開，注意不要使用無意義的註釋
# 正确的写法 x = x + 1 # 边框加粗一个像素 # 不推荐的写法(无意义的注释) x = x + 1 # x加1
1.3、建議
在程式碼的關鍵部分(或比較複雜的地方),能寫註解的要盡量寫註解
比較重要的註解段, 使用多個等號隔開, 可以更加醒目, 突出重要性
app = create_app(name, options) # ===================================== # 请勿在此处添加 get post等app路由行为 !!! # ===================================== if __name__ == '__main__': app.run()
#2、文件註解（ Docstring）
作為文件的Docstring一般出現在模組頭部、函數和類別的頭部，這樣在python中可以透過物件的__doc__物件取得文件. 編輯器和IDE也可以根據Docstring給出自動提示.
文件註解以""" 開頭和結尾, 首行不換行, 如有多行, 末行必需換行, 以下是Google的docstring風格範例
# -*- 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. """
不要在文件註解複製函數定義原型, 而是具體描述其具體內容, 解釋具體參數和返回值等
# 不推荐的写法(不要写函数原型等废话) def function(a, b): """function(a, b) -> list""" ... ... # 正确的写法 def function(a, b): """计算并返回a到b范围内数据的平均值""" ... ...
對函數參數、返回值等的說明採用numpy標準, 如下所示
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] """
文件註解不限於中英文, 但不要中英文混用
文件註解不是越長越好, 通常一兩句話能把情況說清楚即可
#模組、公有類別、公有方法, 能寫文檔註釋的, 應該盡量寫文檔註釋
