Python学习之代码规范

好看的代码撑起整个颜值

---

命名规范

参考博客python命名规范
命名
module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name.

Python之父Guido推荐的规范

避免名称

1. 单字符名称, 除了计数器和迭代器.
2. 包/模块名中的连字符(-)
3. 双下划线开头并结尾的名称(Python保留, 例如init)

命名约定

1. 所谓”内部(Internal)”表示仅模块内可用, 或者, 在类内是保护或私有的.
2. 用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含).
3. 用双下划线(__)开头的实例变量或方法表示类内私有.
4. 将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.
5. 对类名使用大写字母开头的单词(如CapWords, 即Pascal风格), 但是模块名应该用小写加下划线的方式(如lower_with_under.py). 尽管已经有很多现存的模块使用类似于CapWords.py这样的命名, 但现在已经不鼓励这样做, 因为如果模块名碰巧和类名一致, 这会让人困扰.

参考博客2: 命名规范
文件名
全小写,可使用下划线
函数&方法
函数名应该为小写，可以用下划线风格单词以增加可读性。如：myfunction，my_example_function。
注意：混合大小写仅被允许用于这种风格已经占据优势的时候，以便保持向后兼容。

函数和方法的参数
总使用“self”作为实例方法的第一个参数。总使用“cls”作为类方法的第一个参数。
如果一个函数的参数名称和保留的关键字冲突，通常使用一个后缀下划线好于使用缩写或奇怪的拼写。

全局变量
对于from M import *导入语句，如果想阻止导入模块内的全局变量可以使用旧有的规范，在全局变量上加一个前导的下划线。
注意:应避免使用全局变量

变量
变量名全部小写，由下划线连接各个单词。如color = WHITE，this_is_a_variable = 1
注意：
1.不论是类成员变量还是全局变量，均不使用 m 或 g 前缀。
2.私有类成员使用单一下划线前缀标识，多定义公开成员，少定义私有成员。
3.变量名不应带有类型信息，因为Python是动态类型语言。如 iValue、names_list、dict_obj 等都是不好的命名。

常量
常量名所有字母大写，由下划线连接各个单词如MAX_OVERFLOW，TOTAL。

异常
以“Error”作为后缀。

缩写
命名应当尽量使用全拼写的单词，缩写的情况有如下两种：
1.常用的缩写，如XML、ID等，在命名时也应只大写首字母，如XmlParser。
2.命名中含有长单词，对某个单词进行缩写。这时应使用约定成俗的缩写方式。
例如：
function 缩写为 fn
text 缩写为 txt
object 缩写为 obj
count 缩写为 cnt
number 缩写为 num，等。
前导后缀下划线
一个前导下划线：表示非公有。
一个后缀下划线：避免关键字冲突。
两个前导下划线：当命名一个类属性引起名称冲突时使用。
两个前导和后缀下划线：“魔”（有特殊用图）对象或者属性，例如init或者file。绝对不要创造这样的名字，而只是使用它们。
注意：关于下划线的使用存在一些争议。

特定命名方式
主要是指 xxx 形式的系统保留字命名法。项目中也可以使用这种命名，它的意义在于这种形式的变量是只读的，这种形式的类成员函数尽量不要重载。如
class Base(object):
def init(self, id, parent = None):
self.id = id
self.parent = parent
def message(self, msgid):
其中 id、parent 和 message 都采用了系统保留字命名法。

项目结构

使用专业的项目构建发布工具来构建项目目录. 如 buildout . 其目录结构绝对比自己创建来的漂亮.

buildout

参考博客: buildout使用小结

构建项目结构

参考博客: 创建高质量python工程
设计一个层次清晰的目录结构, 优点:

1. 可读性高: 不熟悉这个项目的代码的人，一眼就能看懂目录结构，知道程序启动脚本是哪个，测试目录在哪儿，配置文件在哪儿等等。从而非常快速的了解这个项目。
2. 可维护性高: 定义好组织规则后，维护者就能很明确地知道，新增的哪个文件和代码应该放在什么目录之下。这个好处是，随着时间的推移，代码/配置的规模增加，项目结构不会混乱，仍然能够组织良好。

目录组织方式
假设你的项目名为foo, 我比较建议的最方便快捷目录结构这样就足够了

说明:
1. bin/: 存放项目的一些可执行文件，当然你可以起名script/之类的也行
2. foo/: 存放项目的所有源代码。(1) 源代码中的所有模块、包都应该放在此目录。不要置于顶层目录。(2) 其子目录tests/存放单元测试代码； (3) 程序的入口最好命名为main.py。
3. docs/: 存放一些文档。
4. setup.py: 安装、部署、打包的脚本。
5. requirements.txt: 存放软件依赖的外部Python包列表。
6. README: 项目说明文件。

除此之外，有一些方案给出了更加多的内容。比如LICENSE.txt,ChangeLog.txt文件等，我没有列在这里，因为这些东西主要是项目开源的时候需要用到。如果你想写一个开源软件，目录该如何组织，可以参考文章

README
每个项目都应该有的一个文件，目的是能简要描述该项目的信息，让读者快速了解这个项目
说明以下几个事项:
1. 软件定位，软件的基本功能
2. 运行代码的方法: 安装环境、启动命令等
3. 简要的使用说明
4. 代码目录结构说明，更详细点可以说明软件的基本原理。
5. 常见问题说明。

在软件开发初期，由于开发过程中以上内容可能不明确或者发生变化，并不是一定要在一开始就将所有信息都补全。但是在项目完结的时候，是需要撰写这样的一个文档的. 可参考Redis源码中README, 里面简洁但是清晰的描述了Redis功能和源码结构

requirements.txt
存在的目的是:
1. 方便开发者维护软件的包依赖。将开发过程中新增的包添加进这个列表中，避免在setup.py安装依赖时漏掉软件包。
2. 方便读者明确项目使用了哪些Python包
文件的格式是每一行包含一个包依赖的说明，通常是flask>=0.10这种格式，要求是这个格式能被pip识别，这样就可以简单的通过 pip install -r requirements.txt来把所有Python包依赖都装好了，具体格式说明：example

setup.py
管理代码的打包、安装、部署问题。业界标准的写法是用Python流行的打包工具setuptools管理,这种方式普遍应用于开源项目中。不过这里的核心思想不是用标准化的工具来解决这些问题，而是说，一个项目一定要有一个安装部署工具，能快速便捷的在一台新机器上将环境装好、代码部署好和将程序运行起来。
最好不要手动进行这些步骤，耗时又容易出错
setuptools的文档比较庞大，刚接触的话，可能不太好找到切入点。学习技术的方式就是看他人是怎么用的，可以参考一下Python的一个Web框架，flask是如何写的setp.py
当然，简单点自己写个安装脚本（deploy.sh）替代setup.py也未尝不可。

配置文件
在上面的目录结构中，没有将conf.py放在源码目录下，而是放在docs/目录下
很多项目对配置文件的使用做法是:
1. 配置文件写在一个或多个python文件中，比如此处的conf.py。
2. 项目中哪个模块用到这个配置文件就直接通过import conf这种形式来在代码中使用配置。

nginx、mysql这些程序都可以自由的指定用户配置。所以，不应当在代码中直接import conf来使用配置文件。上面目录结构中的conf.py，是给出的一个配置样例，不是在写死在程序中直接引用的配置文件。可以通过给main.py启动参数指定配置路径的方式来让程序读取配置内容。当然，这里的conf.py你可以换个类似的名字，比如settings.py。或者你也可以使用其他格式的内容来编写配置文件，比如settings.yaml之类的。

文档
目录结构中有设docs/这个目录，用于存放代码文档。实际过程中，据我观察，80%以上的程序员都没有单独写文档的习惯。一般文档写得比较好的，都是一些开源项目。
在普通的项目中，确实没必要写非常详细的文档，我更赞同的是现在的一种流行的风格: “在代码中写文档”。即在写代码的时候，在代码文件里把软件/模块的简要用法写明。简单有用

另外，多翻翻经典项目的源码是有好处的，比如在python web开发中比较有名的框架: flask, tornado, django 都是类似的结构。