编写更好的Python函数¶

好的命名¶

There are only two hard things in Computer Science: cache invalidation and naming things.
-- Phil Karlton

下面是一个不好的函数名

def get_knn_from_df(df):

此函数名称的第一个问题是使用了首字母缩略词/缩写词。函数命名应该使用完整的英语单词而不是缩写词和非普遍已知的首字母缩略词。缩写单词的唯一原因是为了节省输入，但每个现代编辑器都有自动完成功能，因此只需输入一次全名以后用也不麻烦。缩写是一个问题，因为它通常是特定于领域的。在上面的代码中，knn指的是 “K-Nearest Neighbors”，而df指的是“DataFrame”，即无处不在的pandas数据结构。如果另一个不熟悉这些首字母缩略词的程序员正在阅读代码，那么他几乎无法理解这个名字。关于这个函数的名字还有另外两个小问题：“get”这个词是无关紧要的。对于大多数命名良好的函数，很明显该函数正在返回某些内容，其名称将反映这一点。 from_df也是不必要的，因为需要什么参数可以很容易的从函数参数和函数文档看出来。那么我们如何重命名这个函数呢？

def k_nearest_neighbors(dataframe):

现在，即使是外行也很清楚这个函数计算什么，参数也很清晰。更优雅的解决方案可以使用 Python中的typing模块配合类型注释

from typing import List, Tuple
from scipy import DataFrame
def k_nearest_neighbors(dataframe: DataFrame) -> List[Tuple[int, int]]:
"""
:param {DataFrame} dataframe: 原始数据
:returns {List[Tuple[int, int]]}: 最近邻计算结果
"""

单一原则¶

一个函数只做一件事情

文档清晰¶

虽然每个人似乎都知道 PEP-8，它定义了Python 的样式指南，但似乎很少有人知道 PEP-257，它对文档字符串也有同样的指南。

每个函数都需要一个文档字符串
使用正确的语法和标点符号；写出完整的句子
开始以一句话总结函数的作用
使用规定性而非描述性语言

要养成总是编写文档字符串的习惯，并在为函数编写代码之前尝试编写它们。如果你不能写出一个清晰的文档字符串来描述函数将做什么，这表明你首先需要更多地思考为什么要编写函数

有返回值¶

在Python里即使不显示return，实际上Python也会帮你返回None。函数通常被认为是一个一个的功能单元，不返回任何东西是有点奇怪的

不超过50行¶

没啥说的，太长就要想想怎么重构一下

幂等¶

幂等性保证了可以测试