我的总结——全面的『Python编码规范』

时间 2019-11-17

原文原文链接

本文目的

『动态类型一时爽，代码重构火葬场』，说的是：动态语言在初期开发比较爽，可是到后期维护起来比较困难。Python 做为动态语言之一，天然也会有这样的缺点。其实说『火葬场』，也没有那么严重，只要严格的遵照一组规范，也能作到『重构的时候，也同样爽』。python

不以规矩不成方圆，规范天然是十分重要的，而在动态语言中，尤为重要（不少人拿Python写脚本，基本是为所欲为地写，天然后期维护困难）。所谓『兵马未动粮草先行』，咱们应该在写代码前，就作好充足的 “表面功夫”。编程

本文不涉及哪些

不作『文档复读机』。PEP 8中已经有了的，就不重复了，复述一些“低级（你们都知道了的）” 内容，没啥意思。bash

不迷信权威，这里指『Google Python Guide』，那是适合Google的规范，并非社区规范，其实我以为这份规范既不完整，同时，净是一些『众人皆知』的内容，并不推荐之。框架

不搞宗教信仰，奉承实用主义。好比典型的『import this』，只有我一我的以为不过是一堆空洞的废话吗，何况 Python 标准库中不少地方，也没有作到『import this』中的『simple, explicit, and powerful』。每次各类文章（无节操的营销文章，以各类培训机构为主体）说起这个东西，我真是浑身不自在&尴尬（写代码是很工程很严肃的事情，搞这种玄学干吗呢）。编程语言

适用范围 & 原则

Python 2.7 - Python 3.x 。虽然官方宣布了 Python 2的寿命是2020，并且彷佛如今 Python 3已是主流了。可是同窗，legacy code 可不是说去掉就去掉的，Python 2仍然会存在至关长一段时间。何况，Python 3 有相对于 Python 2 的『killer feature』吗，并无。
以 PEP 8 为蓝本，牢牢团结在 PEP 8 周围。任何非官方的文档，只是参考之（同理，本文亦是某种参考资料）。
PEP 8 已经有了的，就不要重复了。

规范

【强制 + 强制】【挑选『静态检查』工具，并自始至终都严格使用】

简单来讲，就是：
1. Pylint
2. Flake8
3. pytest

一开始就要使用，而且从严使用（发点时间了解这几个工具，带来的收益是无限的，若是你是比较正式的项目的话）。
复制代码

【强制+】【多写UT】

其余编程语言，同理。

有一份UT在手，重构起来，内心放心不少。

Python的话，只须要了解unittest就够了，pytest也能够。
复制代码

【强制】【文件编码 & Unicode】

PS：下面这几条，能帮你避免不少无聊的编码解码问题，因此我以为很重要ide

使用 4 空格缩进，禁用任何 TAB 符号
源码文件使用 UTF-8 无 BOM 编码格式
老是使用 Unix \n 风格换行符
在每个 py 文件头，都添加以下内容：

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

# 只导入 future 空间的这两个特性就够了，其余特性容易形成其余方面的『不兼容』，没有使用的必要性。
from __future__ import (absolute_import, unicode_literals)

因此，你须要了解 editorconfig 这个东西，从根源上统一规范，不符合规范的，直接拒绝 PUSH or MERGE
复制代码

###【强制】【命名】工具

class，function 该如何命名，不赘述，严格照着PEP8作就好了，不用多想。
全局变量（全局变量，通常是常量，咱们认为：凡是全局的，都是常量），应该始终使用全大写，如：

GLOBAL_PUBLIC = "G1"
_GLOBAL_PRIVATE = "G2"

class Person:
    _GLOBAL_IN_CLASS = 'G3'
    

按照这条要求，其实不少库or开源库，都是不符合要求的。为何这么强硬呢？
Python中的变量定义，是不分『声明』、『定义』、『初始化』、『赋值』这几个概念的，因此一个
a = 1
若是没有上下文，你是很难肯定其做用域的，也很难肯定 这究竟是初始化仍是赋值（a已经存在过），
若是全局变量还不用全大写，带来的麻烦只会更多。

若是始终坚持这个原则，将会给代码的可读性带来极大提高。
复制代码

【强制】定义枚举，始终加 Enum后缀；定义异常始终加Exception后缀；定义mixin，始终加Mixin后缀，如

class DirectionEnum:
    UP = 1
    DOWN = 2
    
    
class MyException(Exception):
    pass
class MyError(Exception):
    pass
    
class SomeMixin:
    pass
复制代码

【强制】【强化private的概念】

即：最小知识原则，对外暴露的东西越少越好

翻译成大白话就是：
1. 实例属性，通常定义成private的
2. class，对外提供的方法越少越好
3. module，对外提供的接口越少越好
4. package，对外提供的 module 越少越好

翻译成代码就是：
1. 项目布局
package/
    __init__.py
    _private_mod.py
    public_mod.py    
    
2. 某模块内容
public_mod.py
PUBLIC_GLOBAL = 'G1'
_PRIVATE_GLOBAL = 'G2'
class _Class:
    pass
class PublicClass:
    _PRIVATE_GLOBAL = 'G3'
    
    def __init__(self, name,age):
        self._name = name
        self._age = age
    def public_method(self):
        pass
    def _private(self):
        pass
        

全部东西，一开始就要定义成私有的，等到确实须要开放访问了，才开放出去。
复制代码

【强制&重要】【关注公开接口的复杂性】

最好的接口是这样的，调用者无脑使用
def interface():
    pass
    
次等接口是这样的
def interface(param1):
    pass
    
次次等接口是这样的
def interface(p1, p2):
    pass

最大忍受限度的接口是这样的
def interface(p1, p2, p3='SOME DEFAULT'):
    pass
def interface(p1, *args):
    pass
    
不可接受的接口是这样的
def interface(p1, p2, **kwargs):
    pass

使人无语的接口是这样的
def interface(*args, **kwargs):  
# 尽可能不要使用 **kwargs， 某些流行库有这样的毛病，我是以为：极大地增长了调用者的心理负担，反映了接口设计者的懒惰
    pass
    
一直以为，**kwargs只适用于极少数明确的场合，而且须要辅以很明确的文档说明（解释为何要使用），然而现实是，这个
特性已经被你们滥用了，有必要单独说明之。
复制代码

PS：我一直以为，滥用 **kwargs 的API，几乎都不是好 API，无形增长心理负担。布局

【推荐】【以package去设计命名空间，而不是基于module】

【推荐】【了解以下内容】

__init__.py 的做用

__main__.py 的做用

if __name__ == '__main__': 的做用

Python的命名空间加载机制，即：sys.path sys.modules 的内容
复制代码

【推荐】【合理设计项目目录结构】

若是是使用某种框架（如Django），那么按照框架的规范来；若是是“非框架”项目，则按照以下结构

project
    project/
        __init__.py
        core/
        utils/
        constants/
        
        
        __main__.py
        
    tests/
    docs/
    examples/
    README.md
    .pylintrc
    .flake8
    
复制代码