Clever Geek Handbook

Notation of argument names in function comments

One of the most common dilemmas I have when commenting out code is how to break up the 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 is that the names of the arguments vector

, width

and n

do not differ in any way in this comment and can be confused for plain text. Some other options:

Transmogrify 'vector' to fit in 'width'. No more than "n"

Or maybe:

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

Or even:

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

You understand. Some tools, like Doxygen, enforce this, but what if I'm not using a tool? Is this language dependent?

What do you prefer to use you ?

0


source to share


4 answers


I personally prefer single quotes - your first example. It seems like the closest thing to how certain titles / named entities can be referenced in English text if there is no underscore or italics.



+4


source


I agree with Reuben: the first example is the most read.

Of course, this depends on your personal reading habits. If you are used to reading comments in the style of your third example, you may find this style to be the most readable.



But the first style is closest to how we read and write text in everyday life (newspapers, books). Therefore, this is the one that will be easiest to read for those with no experience in reading your comments.

0


source


It seems like not to use any, and just put the variable names in the text. Or I write all the text in such a way that it explains what the function does, but does not mention the parameters in it. This is in the case when the meaning of the parameters should become clear by itself, when you understand what the function is doing.

0


source


My favorite 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 comes, it will be easy to replace @param with @anythingElse.

0


source






More articles:


All Articles