Python 修改对象或返回修改副本的函数命名规范

Question

在Python中，对于那些可以返回修改后的对象或者只是修改实例的函数，应该怎么命名呢？

假设你想同时实现这两种功能，那么你应该怎么给这些函数命名呢？

举个例子：假设你想为一个图像对象创建一个 crop() 函数。在Ruby中，这个命名规则很简单，如果你返回的是一个副本，就用 crop()，如果你修改的是原始实例，就用 crop!()。

Answer 1

我知道的范围内，Python没有统一的规定。不过，我参与的一个项目有个约定，可能对你有帮助：如果一个函数可以直接修改它的参数，它会有一个叫做copy的参数，用来决定这个函数是对输入的副本进行操作，还是直接在原始数据上修改，默认值是True。

def crop(x, copy=True):
    if copy:
        x = x.copy()
    _do_inplace_crop(x)
    return x

Answer 2

在标准库里，有一些方法，比如 list.sort() 和 list.reverse()，它们会直接修改原来的列表。而像 sorted() 和 reversed() 这样的函数则会返回一个新的东西（reversed() 返回的是一个迭代器，而不是新的列表）。不过，如果用实例方法比用函数更合适，我不会为了遵循这个规则而不这样做。

在NumPy中，很多函数和方法都有一个 out 关键字参数，这个参数可以让你指定输出结果放到一个已经存在的数组里，而不是创建一个新的数组。你甚至可以把 out 数组设置成输入数组之一。

Answer 3

我不太确定有没有具体的指导原则在某些PEP文档里，但根据我对Python核心中某些函数/方法的观察，我个人喜欢用动词变形来命名。比如，受到以下内容的启发：

>>> l = list('hello world')
>>> l
['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']
>>> sorted(l)
[' ', 'd', 'e', 'h', 'l', 'l', 'l', 'o', 'o', 'r', 'w']
>>> l
['h', 'e', 'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd']
>>> l.sort()
>>> l
[' ', 'd', 'e', 'h', 'l', 'l', 'l', 'o', 'o', 'r', 'w']

我会把你的函数命名为 crop() [在原地修改对象] 和 cropped() [返回一个修改后的副本]。

编辑：我不懂Ruby，但在Python中，这两者之间的区别纯粹是约定俗成的（函数/方法的行为和你如何调用它是无关的）。

希望这对你有帮助！