Question

在函数上方使用注释来记录调用函数的人是不是很糟糕？

举个例子：

# Called by foo
def bar(something):
    return something+1

这对我来说是一种糟糕的做法，但我想在绕行之前检查一下，告诉别人不要这样做。

Answer 1

风格不好，风格好 - 太主观了。但是有一些明显的利弊。

显而易见：这是值得维护的。如果bar以外的其他内容调用了foo，或重命名了foo，或者类似的内容，那么文档需要更改，否则会变得令人难以置信地混淆*。

_{*如果你绝对相信这不会发生，这自然不是什么大问题。}

明显的亲：它向人们展示了这个功能的来电者。这可能是也可能不是有用的信息。您使用的工具可能会或可能不会多余。

所以你去吧。权衡明显的专业和明显的骗局，并尝试做出一个好的决定。