Cada vez que escribo una construcción típica de if-else en cualquier idioma, me pregunto cuál sería la mejor manera (en términos de legibilidad y visión general) para agregarle 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?

Yo prefiero cualquiera:

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 explicando lo que verifica su condición a menos que el código no lo indique claramente. Incluso entonces, es mejor reescribir el código para que sea lo más claro posible. Lo mismo ocurre con los cuerpos de los bloques condicionales: si puede hacer la razón para hacer algo obvio, hágalo 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 el código debería decir. Si escribe un comentario como "verifique qué tipo de magia debería suceder" cuando el código podría decirif ($magic == big) {... , los lectores dejarán de leer sus comentarios muy rápidamente. El uso de menos comentarios más significativos da más valor a cada uno de sus comentarios, y es mucho más probable que los lectores presten atención a los que usted escribe.

Elegir nombres significativos para sus variables y funciones es importante. Un nombre bien elegido puede eliminar la necesidad de comentarios explicativos en todo el código. En su ejemplo, $magico tal vez $kindOfMagicparece ser un nombre mejor que $bigdesde entonces, según su ejemplo, se está probando el "tipo de magia", no la "grandeza" de algo.

Di todo lo que puedas en código. Guarde la prosa para los casos que exigen más explicación de la que razonablemente puede escribir en el código.

Prueba con nombres explicativos de variables

Los comentarios pueden ser geniales, pero cuando sea posible, haga que el código se documente automáticamente. Una forma de hacerlo es con nombres explicativos de variables. 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) {
  ...
}

Solo para completar algunos comentarios:

El uso adecuado de los comentarios es para compensar nuestra falta de expresión en código. Tenga en cuenta que usé la palabra fracaso. Lo dije en serio. Los comentarios son siempre fracasos. Debemos tenerlos porque no siempre podemos descubrir cómo expresarnos sin ellos, pero su uso no es motivo de celebración. ( Código limpio de Robert C. Martin )

Por cierto: recomiendo este libro.

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

A veces puede sentir que se necesita una paráfrasis al comienzo de la elserama, pero eso a menudo es una señal de que su thenrama es demasiado grande.

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

Compare su 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 según ese esquema, especialmente si fue usted). Ni siquiera se puede saber si $xse supone que es un booleano. Pero este también es un caso en el que no necesariamente necesita comentarios, si puede 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 cada ~ 10-20 líneas que describe lo que logra el siguiente puñado de líneas en un nivel superior de abstracción (por ejemplo, // Make the right amount of magic happenpara su ejemplo) lo ayudará a mantenerse orientado y le dará a un nuevo revisor una visión de lo que está haciendo y cuándo .

En realidad, a menudo escribo estas frases antes de comenzar a escribir código, para no perder la noción del flujo que se supone que debe tener el segmento.

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

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

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

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 otro lado, 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 #.

Intento usar comentarios dentro del bloque que dicen qué hace ese bloque (su primera muestra).

Donde esto se rompe es cuando se usa elseif. Utilizo Basic para que no haya un bloque final explícito y, a menudo, tengo que comentar qué está comprobando 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

• Mantenga sus bloques condicionales realmente cortos.
• Llame a un método con un nombre descriptivo agradable si parece que su código condicional va a ser más que una simple línea o dos.
• Use nombres descriptivos agradables para sus variables.
• Asegúrese de que la declaración condicional sea clara en su significado, y no ofuscada o 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 declaración if, para aclarar su intención. De lo contrario, realmente no debería ser necesario hacer ningún comentario.

En C ++ o C #, normalmente no comentaría casos simples (cuando está claro lo que está sucediendo), y uso este tipo de estilo para comentar la última cosa ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}