我在注释代码时遇到的最常见的难题之一是如何标记参数名称。我将解释我的意思：
def foo(vector, widht, n=0):
""" Transmogrify vector to fit into width. No more than n
elements will be transmogrified at a time
"""
现在，我的问题是参数名称vector,width和n在该注释中没有以任何方式区分，并且可能与简单文本混淆。其他一些选项：
变形“矢量”以适应“宽度”。不超过'n'
或许：
变形 -vector- 以适应 -width-。不超过-n-
甚至：
变形 :vector: 以适应 :width:。不超过:n:
你明白了。像 Doxygen 这样的工具会强制执行此操作，但是如果我不使用工具怎么办？这种语言依赖吗？
你喜欢用什么？
我个人更喜欢单引号——你的第一个例子。当下划线和斜体均不可用时，它似乎最接近在英文文本中引用某些标题/命名实体的方式。
我同意鲁本的观点：第一个例子是最易读的。
当然，这取决于您个人的阅读习惯——如果您习惯于阅读第三个示例的风格的评论，您可能会发现这种风格最易读。
但第一种风格最接近我们在日常生活中阅读和书写文本的方式（报纸、书籍）。因此，对于没有阅读您评论的经验的人来说，这是最容易阅读的。
有点不使用，只是将变量的名称放在文本中。或者我以这样的方式编写整个文本，它解释了函数的作用，但没有提及其中的参数。在这种情况下，当您了解函数的作用时，参数的含义应该自己清楚。
我最喜欢的选择是写：
def foo(vector, width, n=0):
""" Transmogrify 'vector' to fit into 'width'. No more than 'n'
elements will be transmogrified at a time
@param vector: list of something
@param width: int
@keyword n: int (default 0)
"""
Epydoc recognizes @param (see Epydoc manual), and you can use some fancy regexp to find and print parameters of your function, and hopefully Eclipse will start to show parameters description for Python functions in quick assist some day, and I'm pretty sure that it would follow pattern
@ <keyword> <paramName> <colon> 无论如何，当那一天到来时，用@anythingElse 替换@param 会很容易。