在函数的注释中标记参数名称 [英] Marking-up argument names in comments of functions

问题描述

注释代码时最常见的困境之一是如何标记参数名称。我将解释我的意思：

One of the most common dilemmas I have when commenting code is how to mark-up argument names. I'll explain what I mean:

def foo(vector, widht, n=0):
  """ Transmogrify vector to fit into width. No more than n 
      elements will be transmogrified at a time
  """

现在，我的问题是参数名称向量， width n 在该评论中没有以任何方式区分，并且可能对简单文本感到困惑。其他一些选项：

Now, my problem with this is that the argument names vector, width and n are not distinguished in that comment in any way, and can be confused for simple text. Some other options:

Transmogrify'vector'以适应
'width'。不超过'n'

Transmogrify 'vector' to fit into 'width'. No more than 'n'

或可能：

Transmogrify-vector-以适应
-width-。不超过-n -

Transmogrify -vector- to fit into -width-. No more than -n-

或甚至：

Transmogrify：vector：to fit into
：width :.不超过：n：

Transmogrify :vector: to fit into :width:. No more than :n:

你得到了答案。一些工具，如Doxygen强加这一点，但如果我不使用工具怎么办？这种语言是否依赖？

You get the point. Some tools like Doxygen impose this, but what if I don't use a tool ? Is this language dependent ?

您更喜欢使用什么？

推荐答案

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

I personally prefer single quotes--your first example. It seems closest to how certain titles / named entities can be referenced in English text when neither underlining nor italics are available.

这篇关于在函数的注释中标记参数名称的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！