Python中魔法方法的文档

Question

我最近在阅读各种关于Python的风格指南（比如PEP 8等），但对于一个相对简单的问题，我没有找到明确的答案。

当我重新定义Python的许多魔法方法之一，比如__str__(self)、__le__(self, other)等，是否应该对重新定义的方法进行文档说明？还是说只要假设开发者会去python.org查找现有的文档就可以了？

这和其他代码有点不同，因为很多魔法方法是看不见的。举个例子，如果我定义了__eq__(self, other)，那么最终用户在通过==调用它时，是看不到内部文档说明的。

Answer 1

如果你是说记录这个操作的作用，那只有在这个操作可能让人感到“惊讶”的时候才需要这样做。如果你是说记录它是怎么工作的，那你就应该一直这么做。