[英]Are there conventions for Python module comments?
It is my understanding that a module docstring should just provide a general description of what a module does and details such as author and version should only be contained in the module's comments. 我的理解是,模块文档字符串应该只提供模块所做的一般描述,而作者和版本等细节只应包含在模块的注释中。
However, I have seen the following in comments and docstrings: 但是,我在评论和文档字符串中看到了以下内容:
__author__ = "..."
__version__ = "..."
__date__ = "..."
Where is the correct location to put items such as these? 放置这些物品的正确位置在哪里? What other __[name]__
variables are common to list at the top of modules? 还有哪些其他__[name]__
变量在模块顶部列出?
They are merely conventions, albeit quite widely-used conventions. 它们仅仅是惯例,尽管是广泛使用的惯例。 See this description of a set of Python metadata requirements. 请参阅一组Python元数据要求的此描述 。
__version__
is mentioned in the Python Style Guide . Python样式指南中提到了__version__
。
Regarding docstrings, there's a PEP just for you ! 关于docstrings,有一个PEP只为你 !
The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. 模块的docstring通常应列出模块导出的类,异常和函数(以及任何其他对象),每个对应的摘要。 (These summaries generally give less detail than the summary line in the object's docstring.) The docstring for a package (ie, the docstring of the package's init .py module) should also list the modules and subpackages exported by the package. (这些摘要通常提供的细节少于对象文档字符串中的摘要行。)包的docstring(即包的init .py模块的docstring)也应列出包导出的模块和子包。
I would suggest not to worry about __author__
, __version__
, etc. Those attributes are handled by any decent version control system anyway. 我建议不要担心__author__
, __version__
等。 __version__
,这些属性都由任何体面的版本控制系统处理。 Only add them if you need to have that information on a production system, where the source code has already been exported out of the version control system. 只有在需要在生产系统上具有该信息时才添加它们,其中源代码已经从版本控制系统导出。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.