python中的文档变量答案

【问题标题】：Document variable in pythonpython中的文档变量
【发布时间】：2017-05-01 00:42:55
【问题描述】：

如果在我的软件中间，我有这个变量，我需要解释它是什么以及用于什么，我需要记录这个变量。

我有 JS 的背景，所以我就是这样做的：

/**
 * Explain what the variable is, and what is for.
 * @variable {Object} nameOfVariable
 */
var nameOfVariable = []

以python为例：

# ??
name_of_variable = []

这类事情有约定吗？

非常感谢。

【问题讨论】：

根据我的经验，我通常使用文档字符串记录一个函数，但如果您要记录一个变量，您可以连续使用#，直到您记录它为止。我会参考python.org/dev/peps/pep-0008/#comments
effbot.org/zone/pythondoc.htm

【解决方案1】：

是的，这就是我能找到的

对于函数，您可以添加文档字符串，例如

def some_function():
  """ Write here a one line summary. 

If wanted, then leave a line and write a more detailed one"""

""" 需要正确缩进才能工作

但是，对于在单个变量之后更常见的哈希 #，它们不需要正确缩进。例如

some_variable = Something  # This variable is doing this...

希望对您有所帮助。

【讨论】：

如果我需要记录变量的类型怎么办？
写内联注释时，记得在#前面至少放两个空格。
我认为以下问题和答案会对您有所帮助-stackoverflow.com/questions/7690220/…和stackoverflow.com/questions/3051241/…

【解决方案2】：

PEP257 记录了所谓的 docstrings，它是一个字符串文字，在模块、类、函数或方法的定义中作为第一条语句出现。据我所知，如果你想留下一些关于变量的信息，你可以在它附近留下常规的 cmets。例如：

# This is some variable ...
some_variable = ...

【讨论】：

【解决方案3】：

您可能会发现人们记录了参数、函数返回等等，但变量通常没有记录在python库中。

名称通常应该是不言自明的。

【讨论】：