¿Cuál es una buena manera de comentar las cláusulas if-else? [cerrado]

14

Cada vez que escribo una construcción típica if-else-en cualquier lenguaje, me pregunto cuál sería la mejor manera (en términos de legibilidad y visión general) para agregar comentarios. Especialmente al comentar la cláusula else, los comentarios siempre se sienten fuera de lugar para mí. Digamos que tenemos una construcción como esta (los ejemplos están escritos en PHP):

if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

Podría comentarlo así:

// check, what kind of magic should happen
if ($big == true) {
    // do some big magic stuff
    bigMagic();
} else {
    // small magic is enough
    smallMagic()
}

o

// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
    bigMagic();
}
// small magic is enough
else {
   smallMagic()
}

o

// check, what kind of magic should happen
// if:   do some big magic stuff
// else: small magic is enough
if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

¿Cuáles son sus ejemplos de mejores prácticas para comentar esto?

    
pregunta acme 04.04.2012 - 12:25

9 respuestas

34

Yo prefiero:

if ($magic == big) {
    bigMagic();
}
else {
    smallMagic();
}

o:

if ($magic == big) {
    // big magic requires a big surprise, so I'm telling you about it here
    surprisingThing();
}
else {
    // give a magical feeling even if $magic is noMagicAtAll
    smallMagic();
}

Parece un poco tonto escribir un comentario que explique qué verifica su condición a menos que el código no lo indique claramente. Incluso entonces, es mejor volver a escribir el código para hacerlo lo más claro posible. Lo mismo ocurre con los cuerpos de los bloques condicionales: si puedes hacer la razón para hacer algo obvio, hazlo en lugar de comentar.

No me suscribo a la filosofía de "nunca escribir comentarios", pero sí creo en evitar los comentarios que dicen lo que debería estar diciendo el código. Si escribes un comentario como "verifica qué tipo de magia debería ocurrir" cuando el código pudiera decir if ($magic == big) {... , los lectores dejarán de leer tus comentarios muy rápidamente. El uso de menos comentarios más significativos le da más valor a cada uno de tus comentarios y los lectores tienen más probabilidades de prestar atención a aquellos que escribes.

Es importante elegir nombres significativos para sus variables y funciones. Un nombre bien elegido puede eliminar la necesidad de comentarios explicativos en todo su código. En su ejemplo, $magic o tal vez $kindOfMagic parece un nombre mejor que $big , ya que de acuerdo con su ejemplo, es el "tipo de magia" que se está probando, no el "grande" de algo.

Diga todo lo que pueda en el código. Guarde la prosa para los casos que requieran más explicación de la que puede escribir en código.

    
respondido por el Caleb 04.04.2012 - 12:39
11

Prueba los nombres de las variables explicativas

Los comentarios pueden ser excelentes, pero cuando sea posible, haga que el código se autodocumente. Una forma de hacerlo es con nombres de variables explicativas. Por ejemplo, en lugar de esto:

if (user.has_sideburns && user.can_gyrate) {
  // This user is a potential Elvis impersonator

}

Prefiero una variable con nombre:

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}
    
respondido por el Nathan Long 04.04.2012 - 18:13
3

Solo para completar algunos comentarios:

  

El uso correcto de los comentarios es para compensar nuestra incapacidad de expresarnos en   código. Tenga en cuenta que he utilizado la palabra fracaso. Lo dije en serio. Los comentarios son siempre fallos. Debemos   tenerlos porque no siempre podemos imaginarnos cómo expresarnos sin ellos,   Pero su uso no es motivo de celebración. ( Clean Code por Robert C. Martin )

BTW: Recomiendo este libro.

    
respondido por el CSA 04.04.2012 - 21:53
3

Los comentarios no deberían parafrasear el código sino que explican cosas que no están en el código (cuadro más amplio, por qué, por qué no se eligió una alternativa ...) Y sus comentarios de ejemplo son solo eso: paráfrasis del código .

Es posible que algunas veces sientas que se necesita una paráfrasis al comienzo de la rama else , pero a menudo es una señal de que tu rama then es demasiado grande.

    
respondido por el AProgrammer 04.04.2012 - 15:40
2

En su ejemplo específico, los comentarios probablemente no sean necesarios. Como Caleb mencionado , si el código está escrito claramente y las variables tienen nombres semánticos, si es menos probable que las declaraciones tengan comentarios .

Compara tu fragmento con esto:

if ($x) {
    func1();
} else {
    func2();
}

En este caso, definitivamente querrá usar comentarios para describir lo que representan x, func1 y func2 (y abofetear a la persona que nombró las cosas por ese esquema, especialmente si fue usted). Ni siquiera se puede decir si se supone que $x es un booleano. Pero este también es un caso en el que no necesariamente necesitas comentarios, si puedes refactorizar y cambiar el nombre.

En general, me gusta escribir comentarios para bloques lógicos que describen cosas que el código no puede por sí solo. Una línea de cada 10-20 líneas que describe lo que logran las siguientes líneas en un nivel más alto de abstracción (por ejemplo, // Make the right amount of magic happen para su ejemplo) lo ayudará a mantenerse orientado y le dará a un nuevo revisor información sobre lo que está haciendo. haciendo y cuando.

En realidad, a menudo escribo estas líneas de una línea en antes . Empiezo a escribir código, para no perder de vista el flujo que se supone que tiene el segmento.

Finalmente, si realmente prefieres (o hay un mandato que requiere) comentar las cláusulas en un bloque if, independientemente de la legibilidad del código, te recomiendo:

// Broad description of block
if (something) {
    //Do this because something
    something();
} else {
    //Do this because !something
    somethingElse();
}

Creo que es lo más limpio, porque el comentario se alinea con el código al que pertenece. Un comentario que describa qué código hace debe estar lo más cerca posible del comentario que describe.

    
respondido por el asfallows 04.04.2012 - 15:33
2
if (IsWeekDay(day))
{// weekday -> alarm at 7am
   ...
}
else if(day == DayOfWeek.Saturday)
{// saturday -> alarm at 11am
   ...
}
else
{// (sunday) -> no alarm
   ...
}

Mantengo mis soportes alineados y los coloco justo después del soporte.

[Condition] -> [pseudo-code]

Por otra parte, técnicamente significa que todas las demás condiciones fallaron, por lo que generalmente uso paréntesis.

([Condition]) -> [pseudo-code]

Nota: esto es para C #.

    
respondido por el Jake Berger 04.04.2012 - 17:35
1

Intento y uso comentarios dentro del bloque que dicen lo que hace ese bloque (su primera muestra).

Donde este tipo 'se descompone es cuando se usa elseif . Uso Basic, por lo que no hay un bloque de finalización explícito y, a menudo, tengo que comentar qué es la condición que se encuentra en la línea anterior (con un salto de línea, por supuesto) si es demasiado larga.

'Check XYZ
If Condition1 then
  'We need to do T and S
  DoCodeFor1();

'Check ABC
ElseIf Condition1 then
  'This requires something else to be done
  DoCodeFor2()

Else
  'We have no other option than to...
  DoCodeFor3()

End If
    
respondido por el Deanna 04.04.2012 - 12:55
1
  • Mantenga sus bloques condicionales realmente cortos.
  • Llame a un método con un buen nombre descriptivo si parece que su código condicional va a ser más que una simple línea o dos.
  • Use buenos nombres descriptivos para sus variables.
  • Asegúrese de que la declaración condicional sea clara en su significado y que no esté ofuscada o sea larga. Use un método si ayuda a mantener las cosas limpias y legibles.

Si todo lo anterior falla, agregue un comentario descriptivo muy pequeño antes de la sentencia if, para aclarar su intención. De lo contrario, realmente no debería haber ninguna necesidad de comentar.

    
respondido por el S.Robins 05.04.2012 - 10:33
0

En C ++ o C # por lo general, no comentaría casos simples (cuando está claro lo que está sucediendo), y usaría este tipo de estilo para comentar la final ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}
    
respondido por el dodgy_coder 04.04.2012 - 15:08

Lea otras preguntas en las etiquetas