¿Comentario correcto para colocar argumentos de función booleana que son "falsos"?

De algunos proyectos de código abierto, reuní el siguiente estilo de codificación

void someFunction(bool forget);

void ourFunction() {
  someFunction(false /* forget */);
}    

Siempre tengo dudas sobre lo que falsesignifica aquí. ¿Significa "olvidar", o "olvidar" se refiere a su parámetro correspondiente (como en el caso anterior), y "falso" tiene la intención de negarlo?

¿Qué estilo se usa con mayor frecuencia y cuál es la mejor manera (o algunas de las mejores) para evitar la ambigüedad?

En el código de muestra que publicó, parece que forgetes un argumento de bandera. (No puedo estar seguro porque la función es puramente hipotética).

Los argumentos de la bandera son un olor a código. Indican que una función hace más de una cosa, y una buena función debe hacer solo una cosa.

Para evitar el argumento de la bandera, divida la función en dos funciones que expliquen la diferencia en el nombre de la función.

Argumento de la bandera

serveIceCream(bool lowFat)

Sin argumento de bandera

serveTraditionalIceCream()
serveLowFatIceCream()

editar: Idealmente, no es necesario que mantengas una función con el parámetro flag en absoluto. Hay casos similares a los que Fowler llama una implementación enredada donde la separación completa de las funciones crea código duplicado. Sin embargo, cuanto mayor es la complejidad ciclomática de la función parametrizada, más fuerte es el argumento para deshacerse de ella.

En palabras simples:

• false es un literal
• estás pasando un literal false
• estás diciendo someFunctionque no olvides
• estás diciendo someFunctionque el parámetro olvidar esfalse
• estás diciendo someFunctionque recuerdes

En mi opinión, sería mejor si la función fuera así:

void someFunction(bool remember);

lo puedes llamar

void ourFunction() {
  someFunction(true);
} 

o mantenga el nombre anterior pero cambie la función de contenedor a

void ourFunctionWithRemember() {
  someFunction(false);
} 

EDITAR:

Como dijo @Vorac, siempre esfuérzate por usar palabras positivas. La doble negación es confusa.

El parámetro puede estar bien nombrado; Es difícil saberlo sin saber el nombre de la función. Asumo que el comentario fue escrito por el autor original de la función, y fue un recordatorio de lo que pasa falseen someFunctionlos medios, pero para cualquiera que venga a lo largo después, que es un poco confuso a primera vista.

El uso de un nombre de variable positivo (sugerido en Code Complete ) puede ser el cambio más simple que haría que este fragmento sea más fácil de leer, p. Ej.

void someFunction(boolean remember);

luego se ourFunctionconvierte en:

void ourFunction() {
    someFunction(true /* remember */);
}

Sin embargo, el uso de una enumeración hace que la llamada de función sea aún más fácil de entender, a expensas de algún código de soporte:

public enum RememberFoo {
    REMEMBER,
    FORGET
}

...

void someFunction(RememberFoo remember);

...

void ourFunction() {
    someFunction(RememberFoo.REMEMBER);
}

Si no puede cambiar la firma someFunctionpor alguna razón, el uso de una variable temporal también hace que el código sea más fácil de leer, algo así como simplificar los condicionales al introducir una variable sin otra razón que hacer que el código sea más fácil de analizar por humanos .

void someFunction(boolean remember);

...

void ourFunction() {
    boolean remember = false;
    someFunction(remember);
}

Cambie el nombre de la variable para que tenga sentido un valor bool.

Esto es un millón de veces mejor que agregar un comentario para explicar los argumentos de una función porque el nombre es ambiguo.

Cree un booleano local con un nombre más descriptivo y asígnele el valor. De esa manera el significado será más claro.

void ourFunction() {
    bool takeAction = false;  /* false means to forget */
    someFunction( takeAction );
}    

Si no puede cambiar el nombre de la variable, entonces el comentario debería ser un poco más expresivo:

void ourFunction() {
    /* false means that the method should forget what was requested */
    someFunction( false );
}    

Hay un buen artículo que menciona esta situación exacta ya que se refiere a las API Qt-Style. Allí, se llama The Boolean Parameter Trap y vale la pena leerlo.

La esencia de esto es:

1. Sobrecargar la función para que no se necesite el bool es mejor
2. Usar una enumeración (como sugiere Esailija) es mejor

Este es un comentario extraño.

Desde la perspectiva del compilador, someFunction(false /* forget */);es en realidad someFunction(false);(el comentario se elimina). Entonces, todo lo que hace esa línea es llamar someFunctioncon el primer (y único) argumento establecido en false.

/* forget */es solo el nombre del parámetro. Probablemente no sea más que un recordatorio rápido (y sucio), que realmente no necesita estar allí. Simplemente use un nombre de parámetro menos ambiguo, y no necesitará el comentario en absoluto.

Uno de los consejos del código Clean es minimizar el número de comentarios innecesarios ¹ (porque tienden a pudrirse) y nombrar las funciones y los métodos correctamente.

Después de eso, simplemente eliminaría el comentario. Después de todo, los IDE modernos (como eclipse) muestran un cuadro con código cuando coloca el mouse sobre la función. Ver el código debería aclarar la ambigüedad.

¹ Comentando algún código complejo está bien.

Para aclarar lo obvio, los comentarios pueden mentir. Por lo tanto, siempre es mejor hacer que el código de auto-documentación sin tener que recurrir a los comentarios de explicar, porque una persona (tal vez) cambiará truea falseno actualizar el comentario.

Si no puede cambiar la API, recurro a 2 opciones

• Cambie el comentario para que siempre sea cierto, independientemente del código. Si solo llama a esto una vez, esta es una buena solución, ya que mantiene la documentación local.

     algunaFunción (falso / * verdadero = olvidar, falso = recordar * /); `

• Use #defines, especialmente si lo llama más de una vez.

     #define FORGET true
     #define RECUERDA falso
     algunaFunción (RECUERDA);

me gusta la respuesta acerca de hacer que el comentario sea siempre verdadero , pero si bien es bueno, creo que pierde el problema fundamental con este código: se llama con un literal.

Debe evitar el uso de literales al llamar a métodos. Variables locales, parámetros opcionales, parámetros con nombre, enumeraciones: la mejor manera de evitarlos dependerá del idioma y de lo que esté disponible, pero trate de evitarlos. Los literales tienen valores, pero no tienen significado.

En C #, utilicé parámetros con nombre para aclarar esto

someFunction(forget: false);

O enum:

enum Memory { Remember, Forget };

someFunction(Memory.Forget);

O sobrecargas:

someFunctionForget();

O polimorfismo »:

var foo = new Elephantine();

foo.someFunction();

La denominación siempre debe resolver la ambigüedad de los booleanos. Siempre nombro algo booleano como 'isThis' o 'shouldDoThat', por ejemplo:

void printTree(Tree tree, bool shouldPrintPretty){ ... }

y así. Pero cuando hace referencia al código de otra persona, es mejor dejar un comentario al pasar valores.