Marking-up argument names in comments of functions

Question

Hello,

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
  """

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' to fit into 'width'. No more than 'n'

Or maybe:

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

Or even:

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

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

What do you prefer to use ?

Answer 1

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.

Answer 2

I agree with Reuben: The first example is the most readable.

Of course that depends on your personal reading habits - If you got used to read comments in the style of your third example, you may find that style the most readable.

But the first style is closest to the way we read and write text in day-to-day life (newspapers, book). Therefore it is the one that will be easiest to read for someone who has no prior experience to reading your comments.

Answer 3

In kinda use neither, and simply put the names of the variables in the text. Or I write the whole text in such a way that it explains what the function does, but does not mention the parameters in it. That's in the case when the meaning of the parameters should become clear by itself when you understand what the function does.

Answer 4

My favourite option is to write:

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>  

Anyway, when that day come it will be easy to replace @param with @anythingElse.