Python coding 规范

• 程序不仅要写的正确，而且要写的优雅。

1. 一个规范且优雅的‘.py’文件

#! /usr/bin/env python3
# -*- coding:utf-8 -*-
__author__ = 'XF'

'''A standard and elegant Python script example.'''

# import part

# Class or function part

if __name__ == '__main__':

	# test logic part
	

• 第一部分: Python脚本的头部，包括

#! /usr/bin/env python3：用来指定由哪个解释器来执行当前这个脚本。Windows下不支持这种解释器指定方式，‘Unix-like’系统中（像Linux/OS）支持。

# -*- coding:utf-8 -*-：告诉Python解释器，按照utf-8编码读取源代码，否则，在源代码中写的中文输出可能会乱码。注意 ‘coding’和‘:’之间不能有空格

__author__ = 'XF'：注明这个源文件的作者。当然，对于程序本身没什么影响，加上感觉很Cool(前提是你的代码够漂亮)，哈哈哈~~，你也可以加日期(__date__ = '2020/04/24')或者别的什么

'''A standard and elegant Python script example.''':一段纯文本，简要介绍当前这个脚本文件的功能

---

• 第二部分：Python脚本的躯干，包括

# import part：导入外部依赖，导入顺序尽量遵从：

1. Python标准库模块

2. Python第三方模块

3. 自定义模块

# Class or function part：脚本的功能部分，实现需要的类或者函数

---

• 第三部分：Python脚本的测试部分

if __name__ == '__main__'：

这句代码，对于此脚本的功能没有任何影响，貌似可有可无，But，对于一个规范且优雅的Python脚本却很重要。why?

• Python是一种解释型脚本语言，源程序没有固定的入口，也就是说，解释器在拿到源程序之后，就从第一行开始解释执行了，因此，源程序的任意位置都有可能成为程序的入口，当源程序文件比较大时，debug起来就太难受了；因此，可以加一个类似于程序入口的地方，将此文件中的所有可执行部分均写在这个入口之后，逻辑清晰且易于调试。

• __name__是Python的内置变量，用于指代当前模块。当执行当前模块时，__name__的值为__main__，加入这样一个判断if __name__ == '__main__:'，就能保证在执行当前程序时，已导入的其他模块中if __name__ == '__main__:'之后的可执行部分不被执行。

2. coding时应注意的细节

一、标识符命名规范

1. 类名：首字母大写，采用驼峰式命名风格，私有类可用一个下划线开头

...
class MyClass(object):
	pass
class _MyPrivateClass(object):
	pass
...

2. 函数名：所有字母均小写，采用下划线命名风格

...
def my_first_function():
	pass
...

3. 变量名：首字母小写，驼峰式命名风格和下划线命名风格可灵活使用

...
my_var = '666'
myVar = my_var
...

4. 常量名：所有字母均大写，采用下划线命名风格

...
BASE_DIR = '...'
ROOT_DIR = '...'
...

一些建议:

所有标识符的命名应尽量体现其功能，做到‘见其名知其行(功能)’最好。在变量名有多个单词组成的情况下，尽量少使用单词缩写(常见词例外)，变量名长点有什么关系呢

二、代码风格

1. 缩进：Python通过缩进来区分代码之间的层级，建议统一使用Tap键进行缩进(好多地方说用四个空格缩进，那么五个层级就需要十六个空格，代码没写多少，全敲空格了，一不小心还得重敲，真没试过~~)

...

if ...:
	while ...:
		if ...:
			while ...:
				pass
...

2. 空行：作为模块间的’分隔符’，类外模块之间用两个空行来分隔，类内成员函数之间用一个空行进行分隔

...
class _MyPrivateClass(object):
	pass


class MyClass(object):

	def __init__():
		pass
	
	def getValue():
		pass
	
	def setValue(value):
		pass


def my_first_function():
	pass


def my_second_function():
	pass
...

3. 空格：变量和操作符之间应加一个空格(函数形参除外)，函数形参列表中‘，’之后加空格

...
number = 0
if number + 10 > 0:
	pass


def my_first_function(parma1=1, param2='ok'):
	pass
...

4. 引号：请看这里

三、代码注释

注释的重要性不言而喻，好的代码注释利于代码的传播和学习交流，也增加了代码的’生命周期’。

1. 注释类型

• 行注释：用‘#’，跟在代码之后，与代码之间保留两个空格，‘#’与注释内容之间保留一个空格

• 模块注释：用三个成对的单引号或双引号

2. 怎么写好注释

• 注释内容应尽量详尽，但不要写废话

• 对于行注释，说明代码的功能和执行情况

• 对于函数的注释，首先说明函数的功能，然后介绍函数的形参(包括形参的意义及可接受的数据类型)，最后说明函数的返回值(意义及类型)，可在函数的关键代码处添加行注释。

3. 做工程时应该注意的问题

• 对于不同的应用，应该有很多不一样的细节需要注意，但是，也有一些相同且十分必要的问题需要开发者注意。

1. 整个工程的目录设计

• 这是一个工程开始时需要完成的工作，好的目录结构对于工程的前期实现和后期维护有很多积极的影响。怎么设计目录需要根据具体的应用来确定，但有一个原则需要注意：目录不宜过深或过浅(这里又是一个bug~~)，要尽量体现应用的功能分配。

2. 工程中十分必要的几个文件

ReadMe.md

如果你想别人很快能上手这个工程，这个文件必不可少。它具体应该包含什么呢？答案是：你想让别人通过它了解到什么，你就写什么，至少有下面几项：

• 支持的Python版本

• 整个工程的介绍

• 最快让这个工程跑起来的方法

requirements.txt

这个文件的作用：用来存放此工程所依赖的包，是一个纯文本文件，像这样：

aiohttp==3.6.2
aiomysql==0.0.20
async-timeout==3.0.1
attrs==19.3.0
cffi==1.14.0
chardet==3.0.4
cryptography==2.8
databases==0.2.6

这个文件不需要手动去写，使用下面的命令可以自动生成当前环境所需要的依赖包：

pip freeze >requirements.txt

安装时，使用如下命令：

pip install -r requirements

---

参考资料：

• pip与Pipfile
• 廖雪峰Python教程
• Python代码规范