是否有Python模塊注釋的約定？

Question

我的理解是，模塊文檔字符串應該只提供模塊所做的一般描述，而作者和版本等細節只應包含在模塊的注釋中。

但是，我在評論和文檔字符串中看到了以下內容：

__author__ = "..."
__version__ = "..."
__date__ = "..."

放置這些物品的正確位置在哪里？ 還有哪些其他__[name]__變量在模塊頂部列出？

Answer 1

它們僅僅是慣例，盡管是廣泛使用的慣例。 請參閱一組Python元數據要求的此描述 。

Python樣式指南中提到了__version__ 。

關於docstrings，有一個PEP只為你 ！

模塊的docstring通常應列出模塊導出的類，異常和函數（以及任何其他對象），每個對應的摘要。 （這些摘要通常提供的細節少於對象文檔字符串中的摘要行。）包的docstring（即包的init .py模塊的docstring）也應列出包導出的模塊和子包。

Answer 2

你可以看看：

• Epydoc ，更具體地說是它的預定義字段 。
• 是pydoc

Answer 3

我建議不要擔心__author__ ， __version__等。 __version__ ，這些屬性都由任何體面的版本控制系統處理。 只有在需要在生產系統上具有該信息時才添加它們，其中源代碼已經從版本控制系統導出。