我的 Python 编码规范-优快云博客

本文链接：https://blog.youkuaiyun.com/xufive/article/details/84957425

文章目录

1. 前言
2. python 文件的组成
3. 编码格式声明
4. 缩进
5. 引号
6. 注释
7. 空行
8. 空格
9. 文档字符串
10. 导入模块
11. 命名规范

1. 前言

说起编码规范，很多文章都会提到PEP8这个规范。PEP是Python Enhancement Proposal（Python 增强建议书）的简写。PEP8整个文档引用了很多其他标准，看起来挺复杂的，我从来没有完整读下来过。好在龟叔说过，A Foolish Consistency is the Hobgoblin of Little Minds（尽信书，不如无书），只要保持一致性、可读性，就是一个好的规范。基于PEP8规范的原则，结合开发团队在工作中的养成的习惯，我整理了一份实用的编码规范，推荐给初学者。

2. python 文件的组成

为了便于描述，先上一个 demo，

#!/usr/bin/env python
# -*- coding: utf-8 -*-


"""通常这里是关于本文档的说明（docstring），须以半角的句号、 问号或惊叹号结尾!

本行之前应当空一行，继续完成关于本文档的说明
如果文档说明可以在一行内结束，结尾的三个双引号不需要换行；否则，就要像下面这样
"""


import os, time
import datetime
import math

import numpy as np
import xlrd, xlwt, xlutils

import youth_mongodb
import youth_curl


BASE_PATH = r"d:\YouthGit"
LOG_FILE = u"运行日志.txt"


class GameRoom(object):
    """对局室"""
    
    def __init__(self, name, limit=100, **kwds):
        """构造函数!
        
        name        对局室名字
        limit       人数上限
        kwds        参数字典
        """
        
        pass


def craete_and_start():
    """创建并启动对局室"""
    
    pass


if __name__ == '__main__':
    # 开启游戏服务
    start()

Linux 平台上，一个 python 源码文件应该以下部分组成。Windows 平台上，可以省略第一项。

解释器声明
编码格式声明
模块注释或文档字符串
模块导入
常量和全局变量声明
顶级定义（函数或类定义）
执行代码

3. 编码格式声明

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

# -*- coding: utf-8 -*-

# coding = utf-8

我一直 UTF-8 编码格式，喜欢使用第一种声明方式。

Windows 平台上，编码格式声明必须位于 python 文件的第一行。Linux 平台上，编码格式声明通常位于 python 文件的第二行，第一行是 python 解释器的路径声明。

#!/usr/bin/env python
# -*- coding: utf-8 -*-

4. 缩进

统一使用 4 个空格进行缩进。绝对不要用tab, 也不要tab和空格混用。对于行连接的情况，我一般使用4空格的悬挂式缩进。例如：

var_dict = {
    'name': 'xufive',
    'mail': 'xufive@sdysit.com'
}

5. 引号

引号使用的一般性原则：

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

6. 注释

#号后空一格，段落件用空行分开（同样需要#号）：

    # 块注释
    # 块注释
    #
    # 块注释
    # 块注释

行内注释，至少使用两个空格和语句分开：

age += 1  # 年龄增加一岁

比较重要的注释段, 使用多个等号隔开, 可以更加醒目, 突出重要性：

    server= gogame(room, options)
    
    # =====================================
    # 请勿在此处倾倒垃圾!!!
    # =====================================
    
    if __name__ == '__main__':
        server.run()