Question

我在评论代码时遇到的最常见的两难困境是如何标记参数名称。我会解释我的意思：

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在该评论中没有以任何方式区分，并且可能会混淆为简单文本。其他一些选择：

Transmogrify'vector'适合 '宽度'。不超过'n'

或者也许：

Transmogrify -vector-适合 -宽度-。不超过-n -

甚至：

Transmogrify：vector：to fit into ：宽度：。不超过：n：

你明白了。像Doxygen这样的工具强加了这个，但如果我不使用工具呢？这种语言是依赖的吗？

你更喜欢使用什么？

Answer 1

我个人更喜欢单引号 - 你的第一个例子。当没有下划线或斜体可用时，它似乎最接近某些标题/命名实体在英文文本中的引用。

Answer 2

我同意鲁本：第一个例子是最具可读性的。

当然这取决于您的个人阅读习惯 - 如果您习惯以第三个例子的风格阅读评论，您可能会发现该风格最具可读性。

但第一种风格最接近我们在日常生活中阅读和撰写文字的方式（报纸，书籍）。因此，对于那些没有阅读过您评论经验的人来说，这是最容易阅读的内容。

Answer 3

实际上没有使用，只需将变量的名称放在文本中。或者我用这样的方式编写整个文本，它解释了函数的作用，但没有提到它中的参数。当你理解函数的作用时，参数的含义应该变得清晰。

Answer 4

我最喜欢的选择是写：

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。

在函数的注释中标记参数名称

4 个答案: