使用装饰器修改python文档字符串：这是个好主意吗？

一个python docstring必须作为一个文字字符串给出;但有时对于几个函数（例如，不同的构造函数）具有相似的文档字符串是有用的，或者多个访问方法可能接受相同的参数列表（然后依赖于相同的隐藏方法），因此使用相同的无处不在的描述。对于这种情况，我可以通过分配给__doc__构建一个文档字符串，我通过一个简单的装饰器来完成。该系统工作非常好（在Python 2中），我很高兴它是多么简单，清晰和封装好。使用装饰器修改python文档字符串：这是个好主意吗？

问题：这是个好主意吗？特别是，有没有工具可能会被这种设置混淆（例如，从源代码提取文档而不是从字节代码中提取文档的东西）。该解决方案是否仍然在Python 3中工作？是否有其他原因或情况会导致这种不适宜？

来源

2012-03-16 alexis

“不同的构造函数”？我假设你的意思是某种工厂函数，因为你只能有一个'__init__'。 – 2012-03-16 22:37:57

我不认为“工厂功能”是正确的。我指的是一个类的静态成员，它创建了同一个类的一个实例。它们都是使用直接支持的语言的多态构造函数。但是，工厂功能可能是另一种用例。 – alexis 2012-03-17 10:55:44

我会考虑那些工厂，是的。除了命名空间之外，静态成员函数和免费函数（使用C++术语）之间没有任何区别。尽管Python有独立的“类方法”和“静态方法”概念。 – 2012-03-17 12:21:43

它不应该打破任何工具，它应该对Python的工作3.

如果它不伤害源代码的可读性，即它是好的，你还是可以找到的功能是什么，以及如何使用它。

问题可能是它掩盖了一个糟糕的设计。如果几个方法使用相同的参数列表，则代码应该被重构（创建一个与列表一起工作的对象），而不是通过生成重复的文档字符串来修补。

来源

2012-03-16 22:10:27 jfs

谢谢！很高兴听到。我认为设计是好的：这些方法都调用相同的实现方法，并执行诸如以不同格式返回搜索结果（从对象的内容）。在不同的操作界面上有不同的名称是很好的，无论如何，现有的API都有标准化的名称。关于文档字符串，阅读源代码时很容易看到实现方法。但对于交互式帮助，应该记录接口方法。 – alexis 2012-03-17 11:06:24

重新解答了这个问题，因为我希望听到更多关于此的反馈。没有任何意图！ – alexis 2012-03-17 11:20:27

使用装饰器修改python文档字符串：这是个好主意吗？

回答

相关问题