编码规范

Python 编码规范

Linux 平台上 , 一个python源码文件应该以下部分组成 .

Windows 平台上 , 可以省略第一项

例:
    1. 解释器声明 ;
    2. 编码格式声明 ;
    3. 模块注释或文档字符串 ;
    4. 模块导入 ;
    5. 常量和全局变量声明 ;
    6. 顶级定义 ;
    7. 执行代码 .

编码格式声明 :

通常,编码格式声明是必需的 . 如果 Python 源码文件没有声明编码格式,python 解释器会默认使用 ASCII .
一旦源码文件包含非 ASCII 编码的字符, python 解释器就会报错. 以 UTF-8 为例 ,以下两种都是合乎规则的 . 
例 :
    # -*- coding:utf8 -*-
    # coding = utf-8

Windows 平台上, 编码格式声明必须位于 python 文件的第一行 .
Linux 平台上 , 编码格式声明通常位于 python 文件的第二行 , 第一行是python 解释器的路径声明.
例:
# !/user/bin/env python
# -*- coding: utf-8

缩进 :

统一使用 4 个 空格进行缩进. 绝对不要用 tab , 也不要 tab 和 空格混用. 对于行连接的情况 ,
一般用4空格的悬挂式缩进 .
例:
    var_dict = {
            "name": "xufive",
            "mail": "xufive@sdysit.com"
    }

引号 :

* 自然语言使用双引号
* 机器标识使用单引号
* 正则表达式使用双引号
* 文档字符串 ( docstring ) 使用三个双引号 

注释 :

# 后空一格 , 段落间用空行分开 ( 同样需要 # ) ;
    例 :
        # 块注释
        # 块注释
        #
        # 块注释
        
行内注释 , 至少使用两个空格和语句分开 ;
比较重要的注释段 ,使用多个等号隔开 , 可以更加醒目, 突出重要性 ;
例 :
    server = gogame( room , options)
    
    # ==================================
    #  请勿在此处倾倒垃圾 !!! 
    # ==================================    
    
    if _name__ == '__main__':
        server.run()

空行

* 在二元运算符两边隔空一格 , 算术操作符两边的空格可灵活使用 ,但两侧务必保持一致 ;
* 不要在逗号 , 分号 , 冒号前面加空格 , 但应该在他们后面加 ( 除非在行尾 ) ;
* 函数的参数列表中 , 逗号之后要有空格 ;
* 函数的参数列表中 , 默认值等号两边不要添加空格 ;
* 左括号之后 , 右括号之前不要添加空格 ;
* 参数列表 , 索引或切片的左括号前不应该加空格 .

文档字符串

文档字符串是包 . 模块 , 类或函数里的第一个语句 . 这些字符串可以通过对象的 __doc__ 成员
被自动提取 , 并且被 pydoc 所用.
文档字符串的使用三重双引号 ( """ ) . 
如果文档字符串内容不能在一行内写完 , 首行须以句号 ,问号或惊叹号结尾 ,接一空行,结束的三重双引号必须独占一行 .

导入模块

导入总应该放在文件顶部 , 位于模块注释和文档字符串之后 , 模块全局变量和常量之前 .
导入应该按照从最通用到最不通用的顺序分组, 分组之间空一行 ;
    1. 标准库导入
    2. 第三方库导入 
    3. 应用程序指定导入 
避免如下 :
    from math import *

命名规范

* 模块尽量使用小写命名,首字母保持小写, 尽量不要用下划线 ;
* 类名用驼峰 ( CamelCase ) 命名风格 , 首字母大写 , 私有类可用一个下划线开头 ;
* 函数名一律小写 , 如有多个单词 , 用下划线隔开 ;
* 私有函数可用一个下划线开头 ;
* 变量名尽量小写 , 如有多个单词 , 用下划线隔开 ;
* 常量采用全大写 , 如有多个单词 , 使用下划线隔开 .