003-小白之路-python编码规范

命名规范

程序代码中到处都是标识符，因此取一个一致并且符合规范的名字非常重要

1. 包名：全部小写字母中间可以有点分隔，不推荐使用下划线。作为命名空间，包名应该具有唯一性。推荐采用公司加组织域名的倒置。com.deerlili.test
2. 模块名：全部小写字母。如果是多个单词构成。可以用下划线隔开
3. 类名：采用骆峰命名法。首字母大写
4. 异常名：异常属于类。命名同类命名。但应该使用Error作为后缀。例如FileNotFoundError
5. 变量名：全部小写字母。如果有多个单词构成。可以用下划线隔开，如果变量用于模块和函数内部。则变量名可以有单下划线开头。变量类内部私有使用变量名可以用双下划线开头。不要命名双下划线开头和结尾的变量。这是python保留的。避免使用小写L，大写O与大写I作为变量名
6. 函数名和方法名：命名同变量名
7. 常量名：全部大写字母。如果是由多个单词构成，可以用下划线隔开

注释规范

Python中注释的语法有三种。单行注释、多行注释、文档注释

文件注释

就是在每一个文件开头添加注释，采用多行注释，文件注释，通常包括如下信息。版权信息、文件名、所在模块、作者信息、历史版本信息、文件内容和作用等，可以根据实际修改

#
# 版权所有 2019 XXX科技有限公司
# 许可信息查看LINCENSE.TXT文件
# 描述
#     实现日期基本功能
# 历史版本
#     2019-12-12 创建 deerlili
#     2019-12-13 添加 socket 库
#     2019-12-14 添加 math 库
#

文档注释

1. 就是文档字符串。注释内容，能够生成API帮助文档。可以使用python官方提供的pydoc工具从python源代码文件中提取这些信息，也可以生成HTML。文健，所有公有的模块、函数、类和方法都应该进行文档注释
2. 文档注释规范有些苛刻，文档注释推荐使用一对三重双引号包裹起来，注意不推荐使用三重单引号文档，注释应该位于被注释的模块、函数、类和方法的内部的第一语句。如果文档注释一行能够注释完成，结束的三重双引号也应在同一行。如果文档注释很长。在你背后。第一行注释之后要留一个空行，然后剩下的注释内容换行要与开始三重双引号对齐，最后结束的三重双引号要独占一行，并于开始三重双引号对齐

代码注释

程序代码中处理文档注释时还需要在一些关键的地方添加代码注释文档注释，一般是给一些看不到源代码的人看到帮助文档，而代码注释是给阅读源代码的人参考的代码注释，一般采用单行注释和多行注释

TODO注释

pycharm等ide工具。都为源代码提供了一些特殊的注释，就是在代码中加一些标识，便于ide工具快速定位代码。TODO注释就是其中一种,TODO注释虽然不是python官方所提供的，但是主流的ID工具也都支持TODO注释，有TODO注释解释说明此处有待处理的任务和代码没有编写完成

导入规范

导入语句总是放在文件顶部。位于模块注释和文档注释之后，模块全局变量和常量之前。每一个导入语句只能导入一个模块

import re
import struct
import binascii
不推荐：import re，struct，binascii
from后面根多个是可以的:from codeop import compile_command,CommandCompiler

导入语句应该按照从通用到特殊的顺序，分组顺序是。标准库->第三方库->自己模块。每一组之间有一个空行。而组中模块是按照英文字母顺序排序的

import io
import os
import re
import sys

from html import unescape

from com.pkg import example

代码排版

包括空行、空格、断行和缩进的内容。代码排版内容比较多，工作量很大，也非常重要

1. 空行：用于将逻辑相关的代码段分隔开，可以提高阅读性
2. Import语句前后保留两个空行
3. 函数声明之前保留两个空行
4. 类声明之前保留两个空行
5. 方法声明之前保留一个空行
6. 两个逻辑代码块之间应保留一个空行

空格

代码中有些位置是需要有空格的，这个工作量也很大

1. 赋值符号前后各有一个空格
2. 所有的二元运算符都应该使用空格与操作数分开
3. 一元运算符，算法运算符取反和运算符取反，不隔开
4. 括号内不要有空格，python中括号。包括小括号、中括号、大括号
5. 不要在逗号分号，冒号前有空格。而是要在他们后面有一个空格。除非该符号已经是行尾
6. 参数列表索引和切片的左括号前不应该有空格

缩进

四个空格常被作为缩进排版的一个级别

虽然在开发时，程序员可以使用制表符进行缩，进而默认情况下一个制表符等于八个空格。但是不同的ide工具中，一个制表符与空格的对应个数会有不同，所以不要使用制表符缩进

断行

一行代码中最多79个字符，对于文档注释和多行注释时一行最多72个字符，如果注释中包含URL地址可以不受这个限制。否者，如果超过则需要断行，可以依据下面的一般规范断开

1. 在逗号后面断开

bar = long_fun(name1,name2,
          name3,name4)

2. 在运输符号前面断开

name1 = nam2 * (name3 + name4
- name5) + 4

3. 尽量不要使用续行符“\”,当有括号（大中小括号），则在括号中断行，这样可以不适用续行符

# 例如
return name1 + name2 + name3 \
+ name4
# 可以写成
return (name1 + name2 + name3 
     + name4)