Come si indica una variabile in un commento?

Per rispondere alla tua domanda anziché al tuo esempio: dipende dalla lingua e dal modo in cui la documentazione può essere generata.

In C #, ad esempio, formattare il commento come Adds <paramref name="one" /> to <paramref name="two" /> .

Nelle lingue senza un equivalente o lingue che non hanno una documentazione strutturata per cominciare, io uso i "backtick" per distinguerlo come riferimento al codice perché CommonMark lo renderizzerebbe usando i tag del codice. Tuttavia, ho anche visto ' o " utilizzato per fare riferimento agli elementi del codice.

Naturalmente, puoi sempre cercare di evitare il problema riformulando la descrizione per usare il linguaggio naturale piuttosto che fare riferimento direttamente agli elementi del codice. Ad esempio, Returns the sum of the two numbers .

Commento migliore

"adds one to two"

Nota che il tuo commento previsto non è del tutto corretto. Questo può essere interpretato come two += one; o anche two++; .

Un fraseggio migliore sarebbe "aggiunge uno e due", il che non implica la stesura del valore in two

Migliori variabili

Per il tuo commento previsto, la confusione deriva principalmente dal fatto che tu usi nomi di variabili cattivi.

one e two sono nomi incredibilmente confusi per le variabili intere, ad es.

int one = 5; 
int two = 88; 

Perché continuiamo ad applicare questo approccio alla denominazione:

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

Qual è il valore di infinity ?

È importante notare che se avessi usato a , b , c , ... nomi di variabili, che sono privi di significato nel contesto corrente; avresti comunque dovuto fare i conti, ma sarebbe stato meno confuso.

I nomi dei parametri scelti aggiungi confusione in cima a un significato già mancante. Non va bene.

Questo sarebbe stato meno confuso se avessi usato nomi meno ambigui:

def foo(number1, number2)

Accetterei anche def foo(a, b) se foo è un'operazione matematica.

Una risposta diretta

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

Non per quanto ne so. Ma quando usi nomi di variabili validi, un commento sarà generalmente comprensibile:

//Adds number1 and number2

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

Questi commenti sono piuttosto auto-esplicativi, no? Pensi che avvolgere i nomi delle variabili nei delimitatori aggiungerebbe qualcosa al commento? Puoi dare un esempio significativo di questo?

La tua domanda dovrebbe essere come correggere il codice per renderlo leggibile e non commentare sulla cattiva implementazione.

Cambiare il nome della variabile è refactoring e non un vero cambio di codice, quindi nel tuo caso cambia, usando l'esempio della classe java Math usa due parametri come x y e lascia che il nome della funzione descriva cosa viene fatto dentro come addExact o sum

def sum(x, y):
    return x + y