Question

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.