6

Let's say I have the following function in Python:

def foo(one, two):
    return one + two

And I want to document it with "adds one to two".

However, this is confusing, because I could just mean the function literally adds the number 1 to the number 2 and thus always returns the number 3. (Obviously this is not the case, but it describes my point.)

Is there any industry standard for denoting a variable name in documentation?

Currently I've been doing "adds `one` to `two`" or "adds @param one to @param two", but I'm not sure if either of those are correct or generally understandable to other people reading my code unless I explain it to them.

Pro Q
  • 697

3 Answers3

4

Better comment

"adds one to two"

Note that your intended comment isn't quite correct. This can be interpreted as two += one;, or even two++;.

A better phrasing would be "adds one and two", which doesn't imply storying the value in two

Better variables

For your intended comment, the confusion mainly stems from you using bad variable names.

one and two are incredibly confusing names for integer variables, e.g. 

int one = 5; 
int two = 88;

Because if we keep applying this approach to naming:

int five = one + two + 2;
int sixteen = 10 + five + one;
int zero = sixteen - 16;
int infinity = five / zero;

What's the value of infinity?

It's important to note here that if I had used a, b, c, ... variable names, which are meaningless in the current context; you still would have had to do the math, but it would've been less confusing.

Your chosen parameter names add confusion on top of already lacking meaning. That's not good.

This would've been less confusing had you used less ambiguous names:

def foo(number1, number2)

I would also accept def foo(a, b) if foo is a mathematical operation.

A direct answer

Is there any industry standard for denoting a variable name in documentation?

Not as far as I'm aware. But when you use good variable names, a comment will generally be understandable:

//Adds number1 and number2

//Returns number2 if number1 is negative. Otherwise, returns number1.

These comments are pretty self explanatory, no? Do you think that wrapping the variable names in delimiters would add something to the comment? Can you give a meaningful example of this?

Flater
  • 58,824
3

Your question should be how to fix the code to make it readable and not to comment on bad implementation.

Changing variable name is refactoring and not a real code change, so in your case change, using example from java Math class use two parameters as x y and let function name describe what is done inside as addExact or sum

def sum(x, y):
    return x + y
Ori Marko
  • 303
2

To answer your question rather than your example: it depends on the language and the way documentation can be generated.

In C#, for example, I would format the comment as Adds <paramref name="one" /> to <paramref name="two" />.

In languages without an equivalent or languages that do not have any structured documentation to begin with, I use `backticks` to distinguish it as a code reference because CommonMark would render it using code tags. However, I've also seen ' or " being used to reference code elements.

Of course, you can always try to avoid the problem by rephrasing the description to use natural language rather than referencing code elements directly. For example, Returns the sum of the two numbers.

Vivelin
  • 183