5

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
  • 667
  • 1
  • 7
  • 15
  • 11
    I think the standard is to name variables so that you don't need comments like this. If you need a comment like this, rename the variables first. If there is still some arcane, wonky stuff going on, explain in a comment why it's being done. Don't explain what the code is doing, then you have 2 things to maintain: the code being commented on, and the comments about the code. – Greg Burghardt May 07 '18 at 20:30
  • 2
    "Adds the values contained in one and two" or simply "Returns the sum of the specified values." – John Wu May 08 '18 at 03:35
  • I generally prefer to use arg1 and arg2 for precisely this reason so that saying "adds arg1 to arg2" is clear and concise. – Neil May 08 '18 at 07:17
  • 2
    @GregBurghardt: Self-explanatory code, while the best option, is not always achievable. Sometimes comments are needed. I do agree that OP's example is flawed and would be a non-issue if the variables had been named better; but the core question of how to denote a parameter in a comment is still a valid question, in my opinion. – Flater May 08 '18 at 09:28
  • @Flater, since self-explanatory code is the best option, we should all strive for it, all of the time. So needing to write a comment should be seen as a failure to write self-explanatory code. Sometimes it is necessary, but it should be a tool of last resort only. So whilst an OK question, the correct answer to "Is there any industry standard for denoting a variable name in documentation" is "treat your code as documentation, so use meaningful names". – David Arno May 09 '18 at 10:56
  • 2
    It seems like my example is causing more confusion rather than clarifying my question. I just wanted to know whether or not there is an industry standard for denoting a variable name in documentation, and decided to include an example to help illustrate what I meant. It seems as though my example has some flaws though, (but as some have pointed out, this may because all examples may have flaws.) Overall, I think my question has been answered: No. – Pro Q May 11 '18 at 00:53
  • @Neil I'd note that even the much malighned single letter variable names x, y would be better in this case – jk. May 11 '18 at 10:46
  • @jk Sometimes the result of the calculation *is* Y, adding to the confusion of using Y as an argument name. – Neil May 14 '18 at 06:15

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
  • 44,596
  • 8
  • 88
  • 122
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
  • 1
  • 8
  • Sometimes the parameter names might be the best choice for the readability of function's body, but still be common enough words to require some form of quoting in a comment. – 9000 May 08 '18 at 14:07
  • @9000 is it really important in the comment if it's x and y or 'x' and 'y'? – Ori Marko May 08 '18 at 14:24
  • 1
    For `x` and `y`, it is not; for things like `head` and `tail` (when processing lists), or `left` and `right` (when processing trees), or `user` and `password` (when handling authentication) discriminating between the common word and the variable name may be important. – 9000 May 08 '18 at 14:26
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
  • 173
  • 8