Coding Standards – How to Denote a Variable in a Comment

coding-standardscommentsvariables

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.

Best Answer

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.

Related Topic