¿Cuáles son ejemplos de comentarios que le dicen por qué en lugar de cómo o qué? [cerrado]

En primer lugar, en esta pregunta me gustaría mantenerme alejado de la polémica sobre si los comentarios de código fuente son buenos o malos. Solo estoy tratando de entender más claramente lo que las personas quieren decir cuando hablan de comentarios que te dicen POR QUÉ, QUÉ o CÓMO.

A menudo vemos pautas como "Los comentarios deberían decirle POR QUÉ; el código en sí debería decirle CÓMO". Es fácil estar de acuerdo con la declaración en un nivel abstracto. Sin embargo, la gente generalmente deja esto como un dogma y sale de la habitación sin más explicaciones. He visto esto usado en tantos lugares y contextos diferentes, que parece que las personas pueden ponerse de acuerdo sobre el eslogan, pero parecen estar hablando de cosas completamente diferentes.

Entonces, volvamos a la pregunta: si los comentarios deben decirle POR QUÉ, ¿de qué se trata? ¿Es esta la razón por la cual ese código existe en primer lugar? ¿Es esto lo que debe hacer ese código de pieza? Realmente agradecería si alguien pudiera dar una explicación clara, y luego agregar algunos buenos ejemplos (los malos ejemplos no son realmente necesarios, pero puede agregarlos como contraste).

Hay muchas preguntas sobre si los comentarios son buenos o malos, pero ninguno aborda la pregunta específica de cuáles son buenos ejemplos de comentarios que le digan POR QUÉ.

El ejemplo más común y más distintivo son los comentarios sobre varias soluciones alternativas. Por ejemplo este:

https://github.com/git/git/blob/master/compat/fopen.c :

/*
 *  The order of the following two lines is important.
 *
 *  FREAD_READS_DIRECTORIES is undefined before including git-compat-util.h
 *  to avoid the redefinition of fopen within git-compat-util.h. This is
 *  necessary since fopen is a macro on some platforms which may be set
 *  based on compiler options. For example, on AIX fopen is set to fopen64
 *  when _LARGE_FILES is defined. The previous technique of merely undefining
 *  fopen after including git-compat-util.h is inadequate in this case.
 */
#undef FREAD_READS_DIRECTORIES
#include "../git-compat-util.h"

Seguramente encontrará más ejemplos en las fuentes de Git y Linux; ambos proyectos intentan seguir esta regla.

También recomiendo seguir esta regla aún más estrictamente con los registros de confirmación . Para los comentarios de código puede suceder que corrija el código, pero olvide actualizar el comentario. Con la cantidad de código en el proyecto habitual, se garantiza que sucederá tarde o temprano. Por otro lado, el registro de confirmación está vinculado al cambio particular y puede recuperarse utilizando la funcionalidad "anotar" / "culpar" del sistema de control de versiones. Nuevamente, Git y Linux tienen algunos buenos ejemplos.

Mire, por ejemplo, este compromiso . (no copiando aquí, es demasiado largo). Tiene cuatro párrafos que ocupan casi toda la página (y un poco más de pantalla) que describen exactamente qué estaba mal y por qué estaba mal, y luego continúa y modifica todas las seis líneas. Usan comentarios como este para dos propósitos:

1. Todos los cambios enviados se revisan y el registro de confirmación es lo que tiene que explicar el cambio al revisor.
2. Cuando se encuentra un error, los registros relevantes se recuperan utilizando "pico" o "culpa" para evitar volver al comportamiento anterior también incorrecto.

(nota: me llevó como máximo 10 minutos de exploración aleatoria del repositorio de git encontrar estos dos ejemplos, por lo que sería fácil encontrar más allí)

Un comentario que explica por qué explica el razonamiento detrás del código, por ejemplo:

// We need to sync the values if the temp <doodad> GUID matches one of the active <doodad>'s
// GUID, as the temp <doodad> has the most recent values according to the server and said 
// values might have changed since we added the <doodad>. We want a user to be able to <foo> 
// the <doodad> whenever, which means those values must be accurate.
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

Un comentario que le dice cómo explica qué hace el código.

// Loop through our <doodads> and check for a GUID match. If it matches, copy the new values
// on the <doodad> that matches 
for (doodad in doodads) {
    if ([doodad guid] == [tempDoodad guid]) {
        [doodad updateFromDoodad:tempDoodad];
        break;
    }
}

La diferencia es que un mantenedor puede mirar el primero y decir: "¡Oh, esto podría estar desactualizado!" En el segundo caso, dicho mantenedor tiene un comentario que no le dice nada que el código en sí no revela (suponiendo buenos nombres de variables).

Aquí hay un ejemplo de la vida real de un comentario de por qué, de algún código de iOS en el que trabajé, donde necesitábamos obtener una dirección de puerta de enlace (o una suposición razonable). Podría haber dejado los comentarios que decían cosas como "Inicializar el socket de recepción", pero eso solo le diría a un responsable (o futuro) lo que estaba sucediendo, no por qué tuve que hacer este extraño error para obtener la dirección de la puerta de enlace en el primer lugar.

/*
 We're going to do something really hacky here and use a custom partial
 implementation of traceroute to get our gateway IP address.

 [rant removed - irrelevant to the point]

 There's no good way to get at the gateway address of an iDevice
 right now. So, we have two options (per https://devforums.apple.com/message/644915#644915 ):
 1. Get at and parse the routing table (like netstat -rn, or route -n)
 2. Do a traceroute and grab the IP address for the first hop

 As far as I can tell, the former requires <sys/route.h> from the Mac OS X
 header files, which doesn't seem like a good idea to me. Also, there's a
 thread on the Apple Developer forums that seems to imply that header isn't
 in iOS for a reason (https://devforums.apple.com/message/774731#774731 ).

 So when we send our request with a TTL of one it will survive a single hop
 to the router and return, triumphant, with the router's IP address!

 Viva la kludge!

 PS: Original source was the below SO question, but I've modded it since then.
 http://stackoverflow.com/questions/14304581/hops-tracing-ttl-reciveform-on-ios/14304923#14304923
 */

// Default to using Google's DNS address. We used to try checking www.google.com
// if reachability reported we had internet, but that could still hang on routers
// that had no internet connectivity - not sure why.
const char *ip_addr = [kGoogleDNS UTF8String]; // Must be const to avoid undefined behavior
struct sockaddr_in destination,fromAddr;
int recv_sock;
int send_sock;

// ... more code follows

Me gustaría comenzar mi respuesta con una cita hecha por Jeff Atwood en su publicación de blog El código te dice cómo, los comentarios te dicen por qué :

el mejor tipo de comentarios son los que no necesitas

También afirma que:

Primero debe esforzarse por hacer que su código sea lo más simple posible de entender sin depender de los comentarios como una muleta. Solo en el punto donde el código no se puede hacer más fácil de entender, debe comenzar a agregar comentarios.

Estoy totalmente de acuerdo y en este punto debo agregar que antes de que pueda comenzar a hacer el código lo más simple posible, hago que el código funcione y luego empiezo a refactorizar. Entonces, durante la primera ejecución antes de refactorizar, agregar por qué los comentarios ayudan mucho.

Por ejemplo, si usa 3 bucles anidados con tablas de hash bidimensionales para llenar una tabla de días de la semana mientras analiza datos, es muy fácil perder la noción de lo que hizo alguien o incluso usted mismo si no se observa durante algunas semanas y se refactoriza de repente.

[loop1]6oclock -> [loop2]Monday -> [loop3]stage 1 to 4
         -> tuesday-> stage 1 to 4
         ...
         -> Saturday -> stage 1 to 4
    7oclock -> Monday-> stage 1 to 4
        ....etc.

La parte superior es un ejemplo de cómo funcionarían 3 bucles anidados antes de refactorizar.
También explicar algunas condiciones de la rama puede ayudar a comprender el código mucho mejor con lo que uno estaba pensando en el proceso:

// added a zero before the actual day in order for the days always to be 2 digits long.
if( actualDayFuture < 10 ) 
{ 
     actualDayFuture = padIfSingleDigitDate(actualDayFuture); 
}

Incluso el código simple y obvio funciona bien con los comentarios. Solo para hacer las cosas un poco más obvias, más claras o más fáciles de entender para los colegas e incluso para usted mismo en el mantenimiento del software.

Claro, xp afirma tener un código que se explica por sí mismo, pero ¿duele un comentario de una línea?

También encuentro que las siguientes reglas de este blog son muy útiles:

• Comprende el material antes de escribir
• Escribe como si tu audiencia fuera de cuarto grado
• Piensa en cómo los lectores podrían malinterpretarte

Cualquiera que tenga que volver a su propio código o alguien más o incluso el código heredado sabe que puede ser un dolor de cabeza. Entonces, en lugar de ser perezoso o tratar de ser un súper codificador al no comentar nada o muy poco, ¿por qué no hacer que su propio inseguro o alguno pobre, que tiene que mantener su código, haga que la vida futura sea mucho más fácil siguiendo las reglas citadas?

También se dudan muchas decisiones de programación tomadas durante las revisiones y no siempre está claro por qué algunas partes se escribieron tal cual, incluso si algunas secciones del código son vitales para que un programa funcione debido a un error importante que se encontró cuando el código se utilizó durante años . Entonces, para no aburrirlos completamente con un tl; dr cierre con una última cita de acmqueue :

La documentación previa, clara y extensa es un elemento clave en la creación de software que puede sobrevivir y adaptarse. Documentar con altos estándares disminuirá el tiempo de desarrollo, dará como resultado un mejor trabajo y mejorará el resultado final. Es difícil pedir más que eso de cualquier técnica.

Tiendo a reducir los comentarios a referencias donde una determinada funcionalidad / código se explica más a fondo o explicar por qué se elige una determinada forma de programación.

Teniendo en cuenta que otros programadores con habilidades similares usan o leen su código, es importante comentar si usa una forma diferente de lo esperado para lograr algo. Entonces puede explicar en un comentario por qué elige de esta manera.

Por ejemplo, si puede utilizar dos sensores diferentes en un dispositivo Android y uno de ellos no satisface sus necesidades, puede explicar en el comentario por qué eligió el otro.

Por lo tanto, el "por qué" debería dar una justificación sobre sus elecciones.

Los comentarios deben indicarle qué no hace el código, no necesariamente delineado por POR QUÉ , CÓMO o QUÉ . Si tiene buenos nombres y funciones bien delineadas, es muy posible que el código le diga exactamente lo que está sucediendo. Por ejemplo:

List<LightMap> maps = makeLightmaps(receivingModels);
TrianglePartitioner partition = new Octree(castingTriangles);
List<Photon> photons = firePhotons(lights, partition);

if (photons.Count > 0)
{
      PhotonPartitioner photonMap = new KDTree(photons);
      gatherPhotons(maps, photonMap, partition, lights);
}

Este código realmente no necesita comentarios. Los nombres de función y tipo hacen que sea fácil de entender.

A veces, sin embargo, puede ser difícil o imposible crear un código fluido como el anterior. Por ejemplo, el siguiente fragmento de código es para encontrar un punto estadísticamente aleatorio en una esfera. La matemática es bastante opaca, por lo que un comentario con un enlace a la explicación es para ayudar a decir CÓMO funciona. Esto se puede incluir en una función para decir LO QUE hace sin necesidad de un comentario si es necesario más de una vez, de lo contrario, el título del enlace también ayuda en ese departamento.

double randomA = localGenerator.NextDouble();
double randomB = localGenerator.NextDouble();

//http://mathworld.wolfram.com/SpherePointPicking.html
double theta = 2 * Math.PI * randomA;
double phi = Math.Acos(2 * randomB - 1);

Vector3 randomDirection = new Vector3(Settings.ambientRayLength * (float)(Math.Cos(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)(Math.Sin(theta) * Math.Sin(phi)),
                                      Settings.ambientRayLength * (float)Math.Cos(phi));

Otro ejemplo de cuándo los comentarios le dicen lo que no hace el código es para explicar una decisión. En el siguiente ejemplo, el código no bloquea una variable no local de subproceso dentro de un fragmento de código roscado. Hay una razón para esto y el comentario explica POR QUÉ . Sin el comentario, podría considerarse un error, o simplemente no ser notado.

Random random = new Random();
Parallel.For(0, maxPhotons, delegate(int photonIndex, ParallelLoopState state)
{
    ...
    //I don't actually care if this random number is unique between threads, threadsafty is not that big of a deal
    //  in this case and locking the random object could cause a lot of lock contention
    while (random.NextDouble() > reflectProbability)
    {
        ...
    }
    ...
}

Quizás, podría mejorarse decir por qué el objeto aleatorio no se crea dentro del bucle paralelo en primer lugar. Si no hay razón, también podría hacer que alguien se presente y se dé cuenta de que toda la idea es estúpida y es un buen lugar para refactorizar.

Puede ser útil reconocer diferentes tipos de "por qué", especialmente:

• Motivos por los que el código que parece demasiado complejo no funcionaría si se simplifica (por ejemplo, puede ser necesario un tipo de letra aparentemente superfluo para garantizar que el código funcione en algunos casos de esquina).

• Motivos por los que una operación simple en particular que parece peligrosa es realmente segura (por ejemplo, "Nuestra rutina de obtención de datos informará que un elemento ficticio pasado el último es menor que cualquier otra cosa, y el elemento posterior es mayor; cualquier elemento que deba clasificarse antes de otro, en una secuencia ascendente o descendente consistente, tendrá al menos un elemento más (posiblemente ficticio) que lo siga ").

En muchos casos, un comentario del segundo tipo en una parte del código puede "coincidir" con un comentario del primer tipo en otro (por ejemplo, "Si bien parece que esta secuencia de operaciones podría simplificarse, la rutina de Fitz depende de el Wongle no se Woozled hasta después de que el Bandersnatch ha sido Blarped ")

No olvides que si estás escribiendo un programa, no solo estás escribiendo cosas al azar, sino que lo estás haciendo porque tienes un modelo de lo que quieres , ya sea en un documento formal o solo en tu cabeza. Las cosas en tu cabeza son tan reales como el software / datos en una computadora (y es muy probable que contengan errores).

Alguien que lea su código puede no tener ese modelo en su cabeza, por lo que los comentarios pueden servir para decirles cuál era el modelo y cómo se relaciona el código. Creo que eso es lo que se entiende por "por qué". Ciertamente, es bueno hacer que el código en sí sea lo más autoexplicativo posible, pero eso no siempre es lo suficientemente bueno. Ejemplo:

// transform the x,y point location to the nearest hexagonal cell location
ix1 = (int)floor(0.5 + x + y/2);
iy1 = (int)floor(0.5 + y);

Además de eso, el modelo cambia con el tiempo, y esos cambios tienen que transferirse al código. Por lo tanto, los comentarios no solo deben decir "por qué" hay algo en el código, sino que también es importante cómo cambiarlo en respuesta a los cambios anticipados del modelo. Ejemplo:

// to change to square cell locations, remove the "+ y/2" in the above code

Creo que el propósito de los comentarios a veces se descuida.

No todos mis comentarios son del tipo "por qué", pero muchos sí.
Estos son ejemplos de un archivo fuente (Delphi):

// For easier access to the custom properties:

function GetPrivate: Integer;   // It's an integer field in the external program so let's treat it like that here

// The below properties depend on the ones above or are calculated fields.
// They are kept up-to-date in the OnEventModified event of the TTSynchronizerStorage
// or in the ClientDataSet.OnCalcFields of the TcxDBSchedulerStorage.DataSource.DataSet
property IsModified       : Boolean   read GetIsModified   write SetIsModified;
property IsCatTT          : Boolean   read GetIsCatTT      write SetIsCatTT;
property IsSynced         : Boolean   read GetIsSynced     write SetIsSynced;

lLeftPos := pos(' - [',ASubject); // Were subject and [shiftnaam:act,project,cust] concatenated with a dash?

// Things that were added behing the ] we will append to the subject:

// In the storage the custom value must also be set for:
Self.SetCustomFieldValueByname(cCustFldIsCatTT,Result);

// When we show the custom fields in a grid, the Getters are not executed,
// because the DevEx code does not know about our class helpers.
// So we have two keep both properties synchronized ourselves:

// lNewMasterEvent was set to usUpdated, overwrite because we added:
if ARepair then
  lNewMasterEvent.CustUpdateStatus := usRecreated

// The source occurrence date may have bee changed. Using GetOriginalDate we can retrieve the original date,
// then use that for creating a target occurrence (and update its date):

lNewTTOccurrence.CustSyncEntryID := cSyncEntryID0;    // Backward compatibility with old sync methode

// Single event became recurring or vice versa; replace entire event

// In contradiction to CopySingleEventToTimeTell, CopyMasterEventToTimeTell does not have a ANewStatus parameter
// because master events are always added.

Tenga en cuenta que (my) por qué los comentarios generalmente preceden al código que lo hará (por lo tanto, termina con dos puntos).

Tengo algunos comentarios que explican solo lo que está sucediendo, por ejemplo, cuando un proceso tiene muchos pasos que tienen una agrupación lógica (y el código no se refactoriza para mostrar eso automáticamente), comentaré como:

// Step 1. Initialization

Entiendo el POR QUÉ como la razón por la que haces algo de una manera posiblemente extraña o tal vez ilógica, debido a las circunstancias dadas que lo requieren. El CÓMO se puede ver en el código mismo, no importa cuán extraño sea, incluso si el código no tiene "sentido". El QUÉ es probablemente mejor dicho en el comienzo de la documentación de la clase / función. Eso le permite agregar el POR QUÉ , donde explica todo lo que no está incluido en el CÓMO y QUÉ, y las formas peculiares que debe tomar debido a razones que están fuera de su control.

Por supuesto, no siempre es el caso, fuera de la tierra de unicornios y arcoiris ...

CÓMO:

foreach($critters as $creature) {
   $creature->dance();
}

QUÉ:

/* Dancing creatures v1.0
 * 
 * The purpose of this is to make all your critters do the funky dance.
 */

foreach($critters as $creature) {
  $creature->dance();
}

POR QUÉ:

// We had to store the items in an array of objects because of _____ (reason)
foreach($critters as $creature) {
   $creature->dance();
}

Aprendí SIEMPRE a escribir comentarios en los archivos de encabezado de C ++ (ya que no siempre está claro QUÉ hace una función, aunque el nombre da una buena pista) especialmente si pasa una API a otros desarrolladores o usa una herramienta para autodoc como doxygen.

Entonces, para mí, un comentario típico se parece a

/*** Functionname
/*   What happens here
/*  [in] Params
/*  [out] params
/*** 

La única vez que utilicé los comentarios POR QUÉ es algo que es difícil de entender y, a veces, incluso para el programador, como "¡NO TOQUE ESTO! Porque ..." o "EL PROGRAMA SE DESPLAZARÁ SI LA BORRADO ES ..."

Las soluciones, los hacks y el comportamiento extraño califican para los criterios de WHY en mis ojos ...

Un ejemplo muy bueno e incluso divertido es esta "solución" para un código desordenado escrito por una persona llamada Richard, alguien más lo envolvió y explicó por qué en los comentarios ... https://stackoverflow.com/a/184673/979785

Desafortunadamente, hay bastantes ocasiones en las que se ve obligado a envolver toro **** porque no puede tocar el original, ya sea porque "siempre ha sido así" o porque no tiene acceso o ... bueno, usted No tengo tiempo para arreglar el original para el propósito realmente no califica para los gastos generales.

Se supone que el código especifica el plan de ejecución. De esa forma, el seguidor del programa (o el compilador) puede averiguar qué hacer y cómo hacerlo. Lo que se divide en pasos que el seguidor del programa puede seguir. Los pasos primitivos son el cómo.

La intención del codificador es otro asunto. En un código simple, claro y directo, la intención es obvia. Cualquier lector humano razonablemente competente llegará a la intención de un bloque de código, simplemente leyendo el código. La mayoría del código debería leer así.

Ocasionalmente, la relación entre intención y plan es oscura. El código revela el qué y el cómo, pero no el por qué. Ahí es cuando los comentarios que revelan la intención valen la pena. La intención del programador es el por qué.

Tener este problema ahora mismo vadeando a través de procedimientos almacenados y puntos de vista contra un modelo de datos complejo y algo complicado.

Hemos hecho (numerosos) selecciones como "Caso cuando x.account no es nulo y x.address en (seleccione la dirección de fedex) luego x.account más y.account end" en todo momento y se espera productividad aunque no hay tiempo en todo para leer todo el código fuente. Y este tipo de ejemplo tiene sentido, pero sigue siendo inescrutable.

Los comentarios explican por qué si en fedex, entonces x y si no, y - arroja luz sobre todo el sistema y cuando leemos lo suficiente, comenzamos a obtenerlo. Y esto está demasiado simplificado y hay cientos o miles de declaraciones similares. Mi corazón brilla con entusiasmo hacia quien sea que el amable desarrollador de 2007 fue quien puso esos por qué.

Entonces, sí, los complejos modelos de datos complicados y las vistas peludas y el procedimiento almacenado con múltiples rutas válidamente nombradas, por favor, por amor de Dios, díganos por qué.

Acabo de escribir este comentario; Es un ejemplo concreto de explicar por qué una línea de código es lo que es, y en particular por qué la cambié.

El método examina los datos almacenados y evalúa si están completos hasta el día de hoy en un extremo, y hasta la fecha de inicio en el otro extremo.

// In principal, this should be ">=", as we may have data up to the account start
// date but not complete for that day; in practice, 98% of the time if we have
// data for the start date it *is* complete, and requerying it would be a waste
// of time.
while (endDate > accountStartDate)
    ...

Como probablemente pueda adivinar, el operador mayor que había sido mayor o igual. El comentario explica por qué el antiguo valor tiene sentido y por qué el nuevo valor es mejor. Si alguien mira esto en el futuro, verá que el uso de ">" no es un descuido, sino una optimización. Luego pueden cambiarlo o dejarlo, según la necesidad en ese momento.