引言：每天習以為常的Python程式碼，是否符合Python的規範？想寫出Pytonic風格的程式碼，卻不知道如何開始？

這個“Python程式碼規範”系列將會解決這些規範性的問題。

注：本程式碼規範基於PEP8, 在PEP8的基礎上做了一些改動。

註釋和文件

程式碼註釋和文件(docstring)的規範，參考並綜合了PEP257、Google Python Style Guide和Numpy的文件標準。

註釋

文件註釋（Docstring）

作為文件的Docstring一般出現在模組頭部、函式和類的頭部，這樣在python中可以通過物件的doc物件獲取文件。編輯器和IDE也可以根據Docstring給出自動提示。

文件註釋以 """ 開頭和結尾，首行不換行，如有多行，末行必需換行，以下是Google的docstring風格示例：

# -*- coding: utf-8 -*-"""Example docstrings.This module demonstrates documentation as specified by the `Google PythonStyle Guide`_. Docstrings may extend over multiple lines. Sections are createdwith 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.pySection breaks are created by resuming unindented text. Section breaksare 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] """

文件註釋不限於中英文，但不要中英文混用。文件註釋不是越長越好，通常一兩句話能把情況說清楚即可。模組、公有類、公有方法，能寫文件註釋的，應該儘量寫文件註釋。

To be continued.