Python项目的一些规范和工具

【背景】

        无规矩不成方圆，好的编程规范和习惯好处多多（此处自行脑补）。开始接触python也有2周的时间了，也写了几个小工具。是时候不忘初心、回到最开始的地方，看看python的一些好的规范和编程习惯。

        工欲善其事必先利其器，好的工具可以事半功倍。

【目标】

        梳理一些好的python规范，本次梳理python项目目录规范和编码规范。

        梳理一下常用的工具。

【目录规范】

        假如工程名称pyProject（工程名没有一定的规范，参考了一些大型公司的开源项目命名，有写缩写的、有全称的，有驼峰形式的、有横线隔开的，看自己的喜好了，但最好是看到项目名称就知道项目的内容例如FDM(FreeDownloadTool)或者起一个代号例如eclipse。）

        >整个目录规范如下，可以适当裁剪和增加（笔者会经常在根目录增加输出文件夹），但最好不要破坏目录结构

pyProject
|- LICENSE
|- README.md
|- TODO.md
|- requirements.txt
|- ChangeLog.txt
|- setup.py
|- bin
|   |-- __init__.py
|   |-- start.py
|- conf
|   |-- config.cfg
|   |-- config.py
|- docs
|   |-- conf.py
|   |-- generated
|   |-- index.rst
|   |-- installation.rst
|   |-- modules.rst
|   |-- quickstart.rst
|   |-- pyProject.rst
|- lib
|   |-- common.py
|- logs
|   |-- error.log
|   |-- info.log
|- pyProject
|   |-- __init__.py
|   |-- exception.py
|   |-- model.py
|   |-- pyProject.py
|   |-- test
|       |-- models.py
|       |-- test_pyProject.py

         >目录说明

         >>LICENSE  授权文件，可根据需要裁剪

         >>README.md 

              软件定位，软件的基本功能。

              运行代码的方法: 安装环境、启动命令等。

              简要的使用说明。

              代码目录结构说明，更详细点可以说明软件的基本原理。

              常见问题说明。

       >>TODO.md 下一步计划

       >>requirements.txt python依赖的包及版本号，可通过python install -m requirements.txt 直接安装

       >>ChangeLog.txt 版本更改日志

       >>setup.py 安装、配置、部署脚本

       >>bin/ 可执行文件路径，尽量不要直接在core代码（vpProject）文件夹下执行

       >>conf/ 配置文件路径，尽量使用.cfg文件动态加载，而不是写死再.py文件里

       >>docs/ 文档路径

       >>lib/ 公共模块路径

       >>logs/ 日志文件夹

       >>core(pyProject)  核心逻辑代码文件夹

       >>core/test  单元测试文件夹，这个文件夹的好处是，可以不用启动整个工程，而是单独进行某个小功能的测试。笔者就经常用，因为没有系统的学习过python，很多功能都得通过这个先进行下简单的测试，再加载再正常工程里。

【编程规范】

>标准头部（windows可省略）

#!/usr/bin/python

>编码

         所有的 Python 脚本文件都应在文件头标上编码集，用于设置编辑器，默认保存为 utf-8 格式。

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

>注释

         注释有两种：

一种是由【#】开头的“真正的”注释，例如，用于表明为何选择当前实现以及这种实现的原理和难点;

另一种是【docstrings】，例如，用于表明如何使用这个包、模块、类、函数（方法），甚至包括使用示例和单元测试。

        坚持适当注释原则：

1）对不存在技术难点的代码坚持不注释，对存在技术难点的代码必须注释；

2）但与注释不同，建议对每一个包、模块、类、函数（方法）写docstrings，除非代码一目了然，非常简单；

3）注释与对应的代码相同缩进

>main函数

       main函数也有两种写法：

def main():
    pass

if __name__ == '__main__'
    pass

>缩进

        统一4个空格

>空格

         1）在二元算术、逻辑运算符前后加空格：如：【a = b + c;】

         2） 在一元前缀运算符后不加空格，如：【if !flg: pass;】

         3） “:”用在行尾时前后皆不加空格，如分枝、循环、函数和类定义语言；用在非行尾时两端加空格，如：【d = {'key' :  'value'}】

         4） 括号（含圆括号、方括号和花括号）前后不加空格，如：【do_something(arg1, arg2)】

         5） 不要在逗号、分号、冒号前面加空格，但应该在它们后面加（除了在行尾）

         6） 不要用空格来垂直对齐多行间的标记，因为这会成为维护的负担（适用于:，#，=等）

> 空行

        适当的空行有利于增加代码的可读性，加空行可以参考如下几个准则：

1） 在类、函数的定义间加空行；

2） 在 import 不同种类的模块间加空行；

3） 在函数中的逻辑段落间加空行，即把相关的代码紧凑写在一起，作为一个逻辑段落，段落间以空行分隔；

> 断行

        坚持行的最大长度不得超过 80 个字符的标准。折叠长行的方法有以下几种方法：

1) 为长变量名换一个短名

2) Python会将圆括号、中括号和花括号中的行隐式的连接起来，你可以利用这个特点。如需要，你可以在表达式外围增加一对额外的圆括号。

3) 在长行加入续行符强行断行，断行的位置应在操作符前，且换行后多一个缩进，以使维护人员看代码的时候看到代码行首即可判定这里存在换行，如：

 if color == WHITE or color == BLACK \
       or color == BLUE: # 注意 or 操作符在新行的行首而不是旧行的行尾
    do_something(color);

   
> 字符串

1) 避免在循环中用+和+=操作符来累加字符串。 由于字符串是不可变的，这样做会创建不必要的临时对象，并且导致二次方而不是线性的运行时间。作为替代方案，你可以将每个子串加入列表，然后在循环结束后用 .join 连接列表。（也可以将每个子串写入一个 cStringIO.StringIO 缓存中）

2) 为多行字符串使用三重双引号而非三重单引号。不过要注意,通常用隐式行连接更清晰，因为多行字符串与程序其他部分的缩进方式不一致。

>命名

        一致的命名可以给开发人员减少许多麻烦，而恰如其分的命名则可以大幅提高代码的可读性，降低维护成本。

>>常量

        常量名所有字母大写，由下划线连接各个单词，如:【THIS_IS_A_CONSTANT = 1】

>>变量

        变量名全部小写，由下划线连接各个单词，如:【this_is_a_variable = 1】

        私有类成员使用单一下划线前缀标识，多定义公开成员，少定义私有成员。

        变量名不应带有类型信息，因为 Python 是动态类型语言。如 iValue、names_list、dict_obj 等都是不好的命名。

>>函数

        函数名的命名规则与变量名相同。

>>类

         对类名使用大写字母开头的单词（如CapWords, 即Pascal风格），不使用下划线连接单词。如：

class ThisIsAClass(object):
    pass

>>模块

        模块名全部小写，对于包内使用的模块，可以加一个下划线前缀，如：【_internal_module.py】

>>包

        包的命名规范与模块相同

>>缩写

        命名应当尽量使用全拼写的单词，缩写的情况有如下两种：

1） 常用的缩写，如 XML、ID等，在命名时也应只大写首字母,如：

class XmlParser(object):
    pass

2）命名中含有长单词，对某个单词进行缩写。这时应使用约定成俗的缩写方式，如去除元音、包含辅音的首字符等方式，例如：
function fn
text txt
object obj
count cnt
number num

>>特殊命名方式

        主要是指 __xxx__ 形式的系统保留字命名法。

        项目中也可以使用这种命名，它的意义在于这种形式的变量是只读的，这种形式的类成员函数尽量不要重载。如:

class Base(object):
    def __init__(self, id, parent =None):
        self.__id__ = id
        self.__parent__ = parent
    def __message__(self, msgid):
        pass

>> 导入格式

        1) import 的次序:

先 import Python 内置模块，再 import 第三方模块，最后 import 自己开发的项目中的其它模块；

这几种模块用空行分隔开来。

        2）每个import应该独占一行。

        3）不要使用 from module import *，除非是 import 常量定义模块或其它你确保不会出现命名空间冲突的模块。

>赋值

        对于赋值语言，主要是不要做无谓的对齐

>语句

        通常每个语句应该独占一行。不过， 如果测试结果与测试语句在一行放得下， 你也可以将它们放在同一行。如果是if语句,只有在没有else时才能这样做。

        特别地，绝不要对 try/except 这样做，因为try和except不能放在同一行。

【工具推荐】

       工具的目的是为了提高效率、降低出错。不要为了用工具而用工具。截止到目前，笔者一直没有用到第三方工具，一直都是用windows自带的notepad和cmd进行编码、测试、运行。效果还不错，就是效率比较低，尤其是讨厌的空格缩进。所以就在网上看了下常用的工具。

       基础工具，IDE+版本管理就行。

       >IDE：pycharm（收费），或者vscode（免费）。

       >版本管理：git

        可选工具

        >conda或者virtulaenv 可以针对不同工程配置不同版本的python及包环境。笔者一直都是手动下载不同的版本到不同的目录，然后利用bat脚本手动cmd set path。用的也挺好，就是有些麻烦。