2

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.

| improve this question | | | | |
  • 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 7 '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 8 '18 at 3: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 8 '18 at 7: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 8 '18 at 9:28
  • 1
    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 0:53
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.

| improve this answer | | | | |
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?

| improve this answer | | | | |
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
| improve this answer | | | | |
  • 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 8 '18 at 14:07
  • @9000 is it really important in the comment if it's x and y or 'x' and 'y'? – user7294900 May 8 '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 8 '18 at 14:26

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.