前言
无规矩不成方圆，代码亦是如此，本篇文章将会介绍一些自己做项目时遵守的较为常用的 Python 代码规范。
命名
大小写
模块名写法: module_name
包名写法: package_name
类名: ClassName
方法名: method_name
异常名: ExceptionName
函数名: function_name
全局常量名: GLOBAL_CONSTANT_NAME
全局变量名: global_var_name
实例名: instance_var_name
函数参数名: function_parameter_name
局部变量名: local_var_name
命名约定
- 函数名，变量名和文件名应该是描述性的，尽量避免缩写，除了计数器和迭代器、作为
try/except 中异常声明的 e 以及作为 with 语句中文件句柄的 f.用单下划线(_)开头表示变量或函数是 protected 的，不应该被外部访问（除了子类）.
注释
函数和方法
一个函数必须要有文档字符串, 除非它满足以下条件:
- 外部不可见
非常短小
简单明了
文档字符串应该包含函数做什么，以及输入和输出的详细描述。通常，不应该描述“怎么做”，除非是一些复杂的算法。文档字符串应该提供足够的信息，当别人编写代码调用该函数时，他不需要看一行代码，只要看文档字符串就可以了。
文档字符串有多种风格，比如 Google 风格和 Numpy 风格，这里比较推荐 Numpy 风格的文档字符串，基本写法如下述代码所示：
def download_song(song_info: SongInfo, save_dir: str, quality=SongQuality.STANDARD) -> str:
""" download online music to local
Parameters
----------
song_info: SongInfo
song information
save_dir: str
directory to save the downloaded audio file
quality: SongQuality
song sound quality
Returns
-------
song_path: str
save path of audio file, empty string when the download fails
Raises
------
AudioQualityError:
thrown when the sound quality is illegal
"""
pass
块注释和行注释
最需要写注释的是代码中那些技巧性的部分，对于复杂的操作，应该在其操作开始前写上若干行注释。对于不是一目了然的代码, 应在其行尾添加注释。为了提高可读性, 注释应该至少离开代码2个空格。
# We use a weighted dictionary search to find out where i is in
# the array. We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.
if i & (i-1) == 0: # True if i is 0 or a power of 2.
另一方面，绝不要描述代码。假设阅读代码的人比你更懂 Python，他只是不知道你的代码要做什么.
# BAD COMMENT: increase i
i += 1
缩进
用 4 个空格来缩进代码，绝对不要用 tab, 也不要 tab 和空格混用。对于行连接的情况，你应该垂直对齐换行的元素, 或者使用 4 空格的悬挂式缩进(这时第一行不应该有参数)。
哎呦不错哦：
# 垂直对齐参数
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 字典内垂直对齐
foo = {
"long_dictionary_key": value1 +
value2,
...
}
# 4 个空格的悬挂缩进，左括号后面没有参数
foo = long_function_name(
var_one,
var_two,
var_three,
var_four
)
# 字典内 4 个空格的悬挂缩进
foo = {
"long_dictionary_key":
long_dictionary_value,
...
}
那种事情不要啊：
# 左括号后不能携带参数
foo = long_function_name(var_one, var_two,
var_three, var_four
)
# 禁止 2 个空格的悬挂式缩进
foo = long_function_name(
var_one,
var_two,
var_three,
var_four
)
# 字典内需要使用悬挂缩进
foo = {
"long_dictionary_key":
long_dictionary_value,
...
}
编写代码时不能缩进过多的层级，一般不要超过 4 层，不然会造成阅读困难。Python 中的缩进一般来自于 if-else、for 和 while 等语句块，一种减少缩进的方法是写 if 就不写 else，比如：
def update_by_ids(self, entities: List[Entity]) -> bool:
""" update multi records
Parameters
----------
entities: List[Entity]
entity instances
Returns
-------
success: bool
whether the update is successful
"""
# 不满足条件直接返回默认值
if not entities:
return True
# 假设这是一堆很复杂的业务代码
db = self.get_database()
db.transaction()
# 创建 sql 语句
id_ = self.fields[0]
values = ','.join([f'{i} = :{i}' for i in self.fields[1:]])
sql = f"UPDATE {self.table} SET {values} WHERE {id_} = :{id_}"
self.query.prepare(sql)
return db.commit()
还可以使用 continue 来减少 for 和 while 中不必要的缩进：
bboxes = []
for contour in contours:
if cv.contourArea(contour) < 500:
continue
x, y, bw, bh = cv.boundingRect(contour)
bboxes.append([x, y, bw, bh])
换行
顶级定义之间空两行，比如函数或者类定义。 方法定义，类定义与第一个方法之间，都应该空一行。函数或方法中，某些地方要是你觉得合适，就空一行，比如在 if-else、for 和 while 的后面空一行，以及在不同的逻辑之间加空行：
def download_cover(url: str, singer: str, album: str) -> str:
""" download online album cover
Parameters
----------
url: str
the url of online album cover
singer: str
singer name
album: str
album name
Returns
-------
save_path: str
save path of album cover, empty string when the download fails
"""
if not url.startswith('http'):
return ''
# request data
headers = {
'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) '
'AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36'
}
response = requests.get(url, headers=headers)
response.raise_for_status()
pic_data = response.content
# save album cover
return Cover(singer, album).save(pic_data)
导包
导入总应该放在文件顶部, 位于模块注释和文档字符串之后, 模块全局变量和常量之前。导入应该按照 标准库 —> 第三方包 —> 项目代码 的顺序导入：
# coding:utf-8
import base64
import json
from pathlib import Path
from typing import Union
import requests
from common.database.entity import SongInfo
from common.url import FakeUrl
from .crawler_base import CrawlerBase, MvQuality
函数长度
不对函数长度做硬性限制。但是若一个函数超过来40行，推荐考虑一下是否可以在不损害程序结构的情况下对其进行分解。因为即使现在长函数运行良好，几个月后可能会有人修改它并添加一些新的行为，这容易产生难以发现的 bug。保持函数的简练，使其更加容易阅读和修改。当遇到一些很长的函数时，若发现调试比较困难或是想在其他地方使用函数的一部分功能，不妨考虑将这个场函数进行拆分。
类型注释
公共的 API 需要注释
对于容易出现类型相关的错误的代码进行注释，比如下述代码的 image 可能为 numpy 数组，也可能是 Image 类型，究竟是哪种类型需要指明：
def draw_bboxes(image: np.ndarray, bboxes: Union[np.ndarray, list], labels: List[str]) -> Image:
pass
可以使用行尾注释 # type:：
persons = [] # type: List[Person]
参数和返回值类型
当函数需要传入或者返回多个值，可以考虑将这些相关的值作为数据成员封装到一个类中。如下述代码所示，使用 python3.7 提供的 dataclass 可以十分方便地创建一个实体类，接着可以传入传出实体类的实例：
from dataclasses import dataclass
@dataclass
class SongInfo:
""" Song information """
file: str = None
title: str = None
singer: str = None
album: str = None
year: int = None
genre: str = None
duration: int = None
track: int = None
track_total: int = None
disc: int = None
disc_total: int = None
create_time: int = None
modified_time: int = None
class SongInfoReader(SongInfoReaderBase):
""" Song information reader """
def read(self, file: Union[str, Path]):
if not isinstance(file, Path):
file = Path(file)
tag = TinyTag.get(file)
file_ = str(file).replace('\\', '/')
title = tag.title or file.stem
singer = tag.artist or self.singer
album = tag.album or self.album
year = self.__get_year(tag, file)
genre = tag.genre or self.genre
duration = int(tag.duration)
track = self._parseTrack(tag.track or self.track)
track_total = int(tag.track_total or self.track_total)
disc = int(tag.disc or self.disc)
disc_total = int(tag.disc_total or self.disc_total)
create_time = int(file.stat().st_ctime)
modified_time = int(file.stat().st_mtime)
return SongInfo(
file=file_,
title=title,
singer=singer,
album=album,
year=year,
genre=genre,
duration=duration,
track=track,
track_total=track_total,
disc=disc,
disc_total=disc_total,
createTime=create_time,
modifiedTime=modified_time
)
class KuWoMusicCrawler:
""" Kuwo music crawler """
def get_song_url(self, song_info: SongInfo) -> str:
if not FakeUrl.isFake(song_info.file):
return song_info.file
# send request for play url
rid = KuWoFakeSongUrl.getId(song_info.file)
url = f'http://www.kuwo.cn/api/v1/www/music/playUrl?mid={rid}&type=convert_url3&br=128kmp3'
response = requests.get(url, headers=self.headers)
response.raise_for_status()
play_url = json.loads(response.text)['data']['url']
return play_url
千万不要图一时方便而把这些字段放在字典或者列表之中，然后作为函数的参数或者返回值。写时一时爽，重构火葬场。
写在最后
如果能遵守上述规范，相信代码不会那么容易散发出难闻的气味。关于更多代码规范，可以参见 Google 开源项目风格指南，本文也参考了指南的部分内容。如果想写出更加优雅的代码，可以阅读设计模式相关的书籍和博客，这里推荐《精通Python设计模式》和教程 Refactoring GURU，以上~~
