【Tool】Python 代码规范

在业务能力中，尽可能保持clean code 不仅仅是视觉上更容易自己理解，逻辑和代码呈现保持一致性和明确性，在公司/组织中进行Code review和项目移交时也更加顺利，代码规范化不仅包括代码本身格式上的标准和一些便于理解的命名规范，更重要的是代码注释文档能力。本文主要参考博客、PEP8标准和 clean code 一书。

PEP8标准

PEP8 是Python 主要版本的标准库代码书写规范。

Ref:PEP8规范CSDN博客

PEP8主要包括以下几个部分：

Code lay-out，代码布局，包括缩进、换行、空行和空格。
Comment，代码注释和文档说明
Naming norm，变量和函数命名规范
Other，编程建议

代码布局

Tab和空格

空格是首选的缩进方式。制表符只能用于与同样使用制表符缩进的代码保持一致。 Python3不允许同时使用空格和制表符的缩进。混合使用制表符和空格缩进的Python2代码应该统一转成空格。

Max Line Length

79，限制编辑器窗口宽度可以使多个文件并行打开，并且在使用代码检查工具(在相邻列中显示这两个版本)时工作得很好。

Blank Line

顶层函数和类的定义，前后用两个空行隔开。类里的方法定义用一个空行隔开。相关的功能组可以用额外的空行（谨慎使用）隔开。一堆相关的单行代码之间的空白行可以省略（例如，一组虚拟实现 dummy implementations）。在函数中使用空行来区分逻辑段（谨慎使用）。

注释规范化

与代码相矛盾的注释比没有注释还糟，当代码更改时，优先更新对应的注释！
注释应该是完整的句子。如果一个注释是一个短语或句子，它的第一个单词应该大写，除非它是以小写字母开头的标识符(永远不要改变标识符的大小写！)。如果注释很短，结尾的句号可以省略。块注释一般由完整句子的一个或多个段落组成，并且每句话结束有个句号。
在句尾结束的时候应该使用两个空格。当用英文书写时，遵循Strunk and White （译注：《Strunk and White, The Elements of Style》）的书写风格。
请使用英文写注释。

关于The element of style书写风格见文档2.

命名规范化

那些暴露给用户的API接口的命名，应该遵循反映使用场景而不是实现的原则。

命名方式有：

以下是常见的命名方式：

b（单个小写字母）
B（单个大写字母）
lowercase 小写字母
lower_case_with_underscores 使用下划线分隔的小写字母
UPPERCASE 大写字母，多用于常量
UPPER_CASE_WITH_UNDERSCORES 使用下划线分隔的大写字母
CapitalizedWords（或者叫 CapWords，或者叫CamelCase 驼峰命名法 —— 这么命名是因为字母看上去有起伏的外观）。有时候也被称为StudlyCaps。注意：当在首字母大写的风格中用到缩写时，所有缩写的字母用大写，因此，HTTPServerError 比 HttpServerError 好。另外，下面这种用前缀或结尾下划线的特殊格式是被认可的（通常和一些约定相结合）：
_single_leading_underscore：（单下划线开头）弱“内部使用”指示器。比如 from M import * 是不会导入以下划线开始的对象的。
single_trailing_underscore：（单下划线结尾）这是避免和Python内部关键词冲突的一种约定，比如：Tkinter.Toplevel(master, class=’ClassName’)
__double_leading_underscore：（双下划线开头）当这样命名一个类的属性时，调用它的时候名字会做矫正（在类FooBar中，__boo变成了_FooBar__boo；见下文）。
__double_leading_and_trailing_underscore__：（双下划线开头，双下划线结尾）“magic”对象或者存在于用户控制的命名空间内的属性，例如：__init__,__import__或者__file__。除了作为文档之外，永远不要命这样的名。

避免大写的O和小写的l
变量名驼峰命名，尽量不要下划线
函数名全小写，可以加下划线
包名模块名全小写
始终要将 self 作为实例方法的的第一个参数。始终要将 cls 作为类静态方法的第一个参数。
防止冲突+_

Readme规范化

参考了Python 标准库，keras，pytorch，OpenAI的NES实现，一个readme开发文档应该包括如下部分，

Title and demo
Installation and Dependency
Usage
Contributing or bug or user chat
Copyright or License
Update log

如果是实现、用法型的应该包括

File Tree
Function Describtion
Quickly overall
API

模板

DEMO
===========================
#### Describution

Eg. This repository contains PyTorch implementations of deep reinforcement learning algorithms and environments.
Eg. keras-rl implements some state-of-the art deep reinforcement learning algorithms in Python and seamlessly integrates with the deep learning library Keras.

Furthermore, keras-rl works with OpenAI Gym out of the box. This means that evaluating and playing around with different algorithms is easy.

Of course you can extend keras-rl according to your own needs. You can use built-in Keras callbacks and metrics or define your own. Even more so, it is easy to implement your own environments and even algorithms by simply extending some simple abstract classes. Documentation is available online.

#### Dependency
node v0.10.28+
redIs ~

#### Installation
1\. 添加系统环境变量
 export $PORTAL_VERSION="production" // production, test, dev


2\. npm install  //安装node运行环境

3\. gulp build   //前端编译

4\. 启动两个配置(已forever为例)
 eg: forever start app-service.js
 forever start logger-service.js
#### Usage/Example


#### File Tree
├── Readme.md                   // help   
├── app                         // 应用   
├── config                      // 配置   
│   ├── default.json   
│   ├── dev.json                // 开发环境   
│   ├── experiment.json         // 实验   
│   ├── index.js                // 配置控制   
│   ├── local.json              // 本地   
│   ├── production.json         // 生产环境   
│   └── test.json               // 测试环境   
├── data   
├── doc                         // 文档   
├── environment   
├── gulpfile.js   
├── locales 
├── logger-service.js           // 启动日志配置   
├── node_modules   
├── package.json   
├── app-service.js              // 启动应用配置   
├── static                      // web静态资源加载   
│   └── initjson   
│       └── config.js         // 提供给前端的配置   
├── test   
├── test-service.js   
└── tools   



#### V1.0.0 Update log
1\. New Func    aaaaaaaaa
2\. New Func     bbbbbbbbb
3\. New Func     ccccccccc
4\. New Func     ddddddddd

#### Reference
#### Contributing
#### Copyright/Licence

规范化工具

Black

pip intsall black
black main.py