comments - para - como comentar en html5

Dónde poner comentarios en una construcción IF THEN ELSE

Question

Nunca decidí cuál es la mejor manera de comentar las construcciones IF-THEN-ELSE, por lo que nunca estandaricé de forma consistente para comentarlas. Aprecio cualquier idea.

Algunas opciones:

un)

IF (blabla) { 
   // this comment explains what happens in the IF case
   dothis();
} else { 
  // this comment explains what happens in the ELSE case
   dosomethingelse();
}

drawback: en el caso de múltiples sentencias dothis (), me gusta comentar los principales bloques, y en ese caso no siempre está claro si el IF-comment pertenece al primer bloque dothis () o al caso completo de IF

o b)

IF (blabla) { // this comment explains what happens in the IF case
   dothis();
} else { // this comment explains what happens in the ELSE case
   dosomethingelse();
}

inconveniente: solo funciona para comentarios cortos. Usualmente comento las construcciones IF-THEN-ELSE si el caso IF y ELSE no está directamente claro desde el código, lo que generalmente requiere un comentario más largo que una línea.

o c)

// if the following happens
IF (blabla) { // then do this
   dothis();
} else { // or else do this
   dosomethingelse();
}

PD: Sé que "el código debe explicarse por sí mismo", pero este no es siempre el caso ...

Answer 1

¿Qué tal este estilo? Usando // comment para la descripción de la sentencia if-else completa, y /* */ comment para la descripción interna. Uso /* */ comment para no confundirme con el comentario interno de la declaración if-else.

    // Process1
    if (cond1-1) {
        /* Process1 > Process1-1 */
        Process1-1();
        // Process1-1 description...
        Process1-1();
        Process1-1();
        ... 

    } else if (cond1-2) {
        /* Process1 > Process1-2 */
        // Process1-2 description...
        Process1-2();
        Process1-2();
        Process1-2();
        ... 

        // Process1-2
        if (cond1-2-1) {
            /* Process1 > Process1-2 > Process1-2-1 */
            Process1-2-1();
            Process1-2-1();
            Process1-2-1();
            ...

        } else if (cond1-2-2) {
            /* Process1 > Process1-2 > Process1-2-2 */
            Process1-2-2();
            // Process1-2-2 description...
            Process1-2-2();
            // Process1-2-2 description...
            Process1-2-2();
            ...

        } else {
            /* Process1 > Process1-2 > Process1-2-else */
            Process1-2-else();
            Process1-2-else();
            Process1-2-else();
            ...
        }

    } else {
        /* Process1 > Process1-else */
        Process1-else();
        Process1-else();
        Process1-else();
        ...
    }

Answer 2

De los docs de docs java para convenciones de código

Comentarios de una sola línea para if-else:

if (condition) {
 /* Here is a single line comment. */
 ...
}

Una línea de comentarios muy cortos para if-else:

if (a == 2) {
   return TRUE; /* special case */
} else {
 return isprime(a); /* works only for odd a */
}

Comentarios de línea múltiple para if-else:

if (condition) {
 /*
  * Here is a block comment.
  */
}

Answer 3

Haría caso a) pero con un poco más de espacio en blanco:

if (blabla) {
   // This explains the whole if case

   // Can comment here for specific block comments
   doThis();
} else {
   // This explains the else case

   // Same again
   doSomethingElse();
}

Answer 4

Nunca lo pensé mucho; personalmente y cuando sea necesario, he puesto comentarios sobre las declaraciones IF y ELSE. Esto me da una buena separación entre los comentarios sobre las declaraciones de la sucursal y los comentarios sobre el código.

// comment about the if statement
if (expression)
{
    // comment about the code
    doSomething();
}
// comment about the else statement
else
{
    // comment about the code
    doSomethingElse();
}

También observo que soy la única respuesta hasta ahora para usar el "estilo abierto de llavero", que podría ser un retroceso en mis días de Pascal, aunque prefiero la justificación visual del comienzo y el final de los bloques de código, así que mi estilo de comentario puede no funcionar para la "comunidad cerrada de estilo de llavero".

Answer 5

Para mí, un comentario sobre el IF explica la declaración IF sí misma. Por ejemplo, si la condición que se prueba es particularmente compleja.

Un comentario en el bloque debajo de IF o ELSE describe qué sucede una vez que se ha evaluado la condición y se ha tomado una decisión.

Así que así:

//Is this a favoured customer and do we have a promotion?
if customer.special() and monthly.hasOffer() {
  //Add discount
  invoice.addDiscount();
} 
else {
  //Add note about favoured customer scheme
  invoice.addNotes(JOIN_OUR_DISCOUNT_SCHEME);
}

Answer 6

Personalmente, creo que es mejor escribir código que no requiera pocos comentarios que digan "about do do x", seguido de "DoX ()". Si es necesario, en lugar de escribir un comentario que diga "do x por y", preferiría escribir un método llamado "DoXBecauseOfY". Si la refactorización posterior elimina la parte "BecauseOfY", entonces tiene más sentido poner un comentario antes de la declaración if , documentando la lógica general.

Por supuesto, debe reducir la cantidad de código dentro de cada bifurcación hasta el punto en que pueda leer todo el enunciado if a la vez.

Answer 7

Use lo que tiene sentido para usted, supongo (a menos que esté trabajando bajo un estándar de codificación que especifique el estilo de comentario). Personalmente no uso (c) porque es inconsistente entre el primero y los siguientes casos. De vez en cuando uso (b) cuando un comentario breve servirá pero generalmente prefiero (a). Si estoy comentando varios subbloques dentro del bloque if, podría dejar una línea en blanco después del comentario del caso:

if (blabla) {
    // here''s a comment about this case

    // comment about this bit of code
    bit_of_code();
    // comment about this other bit of code
    other_bit_of_code();
}

y así.

Answer 8

solo para agregar la respuesta que falta para la ubicación de los comentarios del otro, que en mi opinión es la mejor ubicación para la lectura del código por los siguientes motivos:

• si el comentario se pone por encima del resto, rompe la continuidad if-else
• si se pone dentro se puede mezclar con el comentario de la primera declaración dentro del otro

// match jth arc
if (j < Count)
{
     // arc matched
     if (arcs[j].IsBlue) List.Add(arcs[j])
}
else // all arcs were matched
{
     // check if there more arcs
     if (arcs[j + 1] != null) continue;
}

Se ve muy bien si colapsas los bloques

// match jth arc
if (j < Count)|...|
else // all arcs were matched|...|

Answer 9

// Not very much sure, but here is a snippet of my code

// tweak URL as per query params and hash index positions
if (hasQueryParams && hashPos > -1) {
    // both query params and hash available
    ...
    ...
} else if (hasQueryParams) {
    // only query params available
    ...
    ...
} else if (hashPos > -1) {
    // only hash available
    ...
    ...
} else {
    // neither query params nor hash available
    ...
    ...
}