comments - mejora - enfoque de procesos
¿Cuál es su enfoque personal/comentar? (26)
Duplicar
Un desarrollador con el que trabajo tenía algunas cosas que decir sobre los comentarios que me resultaron interesantes (ver más abajo). ¿Cuál es su enfoque personal / comentar?
"No agrego comentarios al código a menos que sea un encabezado simple o haya un
error de plataforma o una solución de problemas necesaria que no es obvia. El código puede cambiar y los comentarios pueden ser engañosos. El código debe ser
auto-documental en su uso de nombres descriptivos y su lógica
organización - y sus soluciones deberían ser la forma más limpia / simple
para realizar una tarea dada. Si un programador no puede decir qué programa
hace solo leyendo el código, entonces no está listo para alterarlo.
Comentar tiende a ser una muleta para escribir algo complejo o
no es obvio: mi objetivo es escribir siempre código limpio y simple "."Creo que hay algunos campos a la hora de comentar, los de tipo empresarial que piensan que están escribiendo una API y una gran biblioteca de códigos que se usará para las generaciones venideras, el programador artesano que piensa que el código dice es más claro de lo que podría hacer un comentario, y los novatos que escriben código detallado / incierto para tener que dejar notas a sí mismos sobre por qué hicieron algo ".
A veces el código hace exactamente lo que necesita hacer, pero es algo complicado y no sería inmediatamente obvio la primera vez que alguien más lo mirara. En este caso, agregaré un breve comentario en línea que describa el objetivo del código.
También intento dar encabezados de documentación de métodos y clases, lo cual es bueno para la documentación inteligente y autogenerada. De hecho, tengo la mala costumbre de dejar el 90% de mis métodos y clases sin documentar. No tienes tiempo para documentar cosas cuando estás en el medio de la codificación y todo está cambiando constantemente. Luego, cuando termines, no tienes ganas de volver y encontrar todo lo nuevo y documentarlo. Probablemente sea bueno volver cada mes más o menos y simplemente escribir una gran cantidad de documentación.
Agregamos comentarios que proporcionan la documentación de referencia de API para todas las clases / métodos / propiedades públicas / etc ... Vale la pena el esfuerzo porque la documentación XML en C # tiene el bonito efecto de proporcionar IntelliSense a los usuarios de estas API públicas. Los contratos de código de .NET 4.0 nos permitirán mejorar aún más en esta práctica.
Como regla general, no documentamos implementaciones internas a medida que escribimos código a menos que hagamos algo que no sea obvio. La teoría es que mientras escribimos nuevas implementaciones, las cosas están cambiando y es más probable que los comentarios no estén mal cuando se asienta el polvo.
Cuando volvemos a trabajar en una pieza existente de código, agregamos comentarios cuando nos damos cuenta de que está pensando un poco en descubrir qué diablos está pasando. De esta manera, terminamos con comentarios donde es más probable que sean correctos (porque el código es más estable) y donde es más probable que sean útiles (si vuelvo a un fragmento de código hoy, parece más es probable que vuelva a hacerlo mañana).
Comenta tanto como sea necesario, entonces, tanto como lo necesitaré un año después.
Como contratista, sé que algunas personas que mantienen mi código no estarán familiarizadas con las funciones avanzadas de ADO.Net que estoy usando. Cuando corresponda, agrego un breve comentario sobre la intención de mi código y una URL a una página de MSDN que se explica con más detalle.
Recuerdo haber aprendido C # y haber leído el código de otras personas. A menudo me sentí frustrado por preguntas como "¿cuál de los 9 significados del personaje de colon significa esto ?" Si no conoce el nombre de la característica, ¿cómo la busca? (Nota al margen: Esta sería una buena función IDE: selecciono un operador u otro token en el código, haga clic derecho y luego me muestra su parte del idioma y el nombre de la función. C # necesita esto, VB menos).
En cuanto al grupo "No comento mi código porque es muy claro y limpio ", a veces sobreestiman lo claro que es su código inteligente. El pensamiento de que un algoritmo complejo se explica por sí mismo a alguien que no sea el autor es una ilusión.
Y me gusta el comentario de @ 17 of 26 (empahsis agregado):
... leer el código te dirá exactamente lo que está haciendo. Sin embargo, el código es incapaz de decirle lo que se supone que debe hacer.
En general, veo comentarios utilizados para explicar el código mal escrito. La mayoría de los códigos se pueden escribir de forma tal que los comentarios sean redundantes. Dicho esto, me encuentro dejando comentarios en el código donde la semántica no es intuitiva, como llamar a una API que tiene un comportamiento extraño o inesperado, etc.
Escribo comentarios que describen el propósito de una función o método y los resultados que devuelve con el detalle adecuado. No escribo muchos comentarios de código en línea porque creo que mi función y denominación variable son adecuados para comprender lo que está sucediendo.
Desarrollo en muchos sistemas PHP heredados que están terriblemente escritos. Ojalá el desarrollador original hubiera dejado algún tipo de comentarios en el código para describir lo que estaba sucediendo en esos sistemas. Si vas a escribir un código indescifrable o incorrecto que alguien más leerá con el tiempo, deberías comentarlo.
Además, si estoy haciendo algo de una manera particular que no se ve bien a primera vista, pero sé que es porque el código en cuestión es una solución para una plataforma o algo así, entonces comentaré con un comentario ADVERTENCIA .
Esta es mi opinión (basada en varios años de investigación doctoral):
Hay una gran diferencia entre las funciones de comentarios (una especie de cuadro negro, como JavaDocs) y el código real para alguien que leerá el código ("comentarios internos").
La mayoría del código "bien escrito" no debería requerir mucho "comentario interno" porque si funciona mucho, entonces debería dividirse en suficientes llamadas de función. La funcionalidad para cada una de estas llamadas se captura en el nombre de la función y en los comentarios de la función.
Ahora bien, los comentarios sobre las funciones son realmente el problema, y de alguna manera su amigo tiene razón, que para la mayoría de los códigos no existe un incentivo económico para las especificaciones completas de la misma forma que las API populares están documentadas. Lo importante aquí es identificar cuáles son las "directivas": las directivas son aquellas piezas de información que afectan directamente a los clientes y requieren alguna acción directa (y a menudo son inesperadas). Por ejemplo, X debe invocarse antes de Y, no llamar a esto desde fuera de un subproceso de interfaz de usuario, tenga en cuenta que esto tiene un cierto efecto secundario, etc. Estas son las cosas que son realmente importantes para capturar.
Dado que la mayoría de las personas nunca lee documentos de funciones completos, y lee lo que leen, puede aumentar las posibilidades de conocimiento al capturar solo las directivas en lugar de la descripción completa.
Estoy de acuerdo con la teoría del código de auto-documentación, si no puedo decir qué cantidad de código está haciendo simplemente leyéndolo, entonces probablemente necesite una refactorización; sin embargo, hay algunas excepciones a esto, agregaré un comentario si:
- Estoy haciendo algo que normalmente no ves
- Hay importantes efectos secundarios o detalles de implementación que no son obvios, o que no serán el próximo año
- Necesito recordar implementar algo, aunque prefiero una excepción en estos casos.
- Si me veo obligado a hacer otra cosa y estoy teniendo buenas ideas o un momento difícil con el código, agregaré comentarios suficientes para preservar mi estado mental temporalmente
Hay un error trágico con la teoría del "código de auto-documentación". Sí, leer el código te dirá exactamente lo que está haciendo. Sin embargo, el código es incapaz de decirle lo que se supone que debe hacer.
Creo que es seguro decir que todos los errores se producen cuando el código no está haciendo lo que se supone que debe estar haciendo :). Entonces, si agregamos algunos comentarios clave para proporcionarles a los mantenedores información suficiente para saber qué se supone que debe hacer un código, les hemos dado la posibilidad de corregir un montón de errores.
Eso nos deja con la pregunta de cuántos comentarios incluir. Si hace demasiados comentarios, las cosas se volverán tediosas de mantener y los comentarios inevitablemente estarán desactualizados con el código. Si ingresas muy pocos, entonces no son particularmente útiles.
He encontrado comentarios regulares para ser más útil en los siguientes lugares:
1) Una breve descripción en la parte superior de un archivo .h o .cpp para una clase que explica el propósito de la clase. Esto ayuda a los mantenedores a tener una visión general rápida sin tener que pasar por todo el código.
2) Un bloque de comentarios antes de la implementación de una función no trivial que explica el propósito del mismo y detalla sus entradas esperadas, salidas potenciales y cualquier rareza que se espera al llamar a la función. Esto ahorra a los mantenedores futuros tener que descifrar funciones completas para resolver estas cosas.
Aparte de eso, tiendo a comentar cualquier cosa que pueda parecer confusa o extraña para alguien. Por ejemplo: "Esta matriz está basada en 1 en lugar de 0 debido a bla bla".
Los comentarios bien escritos y bien ubicados son invaluables. Los malos comentarios son a menudo peores que no hay comentarios. Para mí, la falta de comentarios indica vagancia y / o arrogancia por parte del autor del código. No importa cuán obvio sea para usted lo que el código está haciendo o cuán fantástico es su código, es una tarea desafiante entrar en un cuerpo de código frío y descubrir qué diablos está pasando. Los comentarios bien hechos pueden hacer una gran diferencia para que alguien se ponga al día con el código existente.
La gran mayoría de mis commnets están en el nivel de clase y el nivel de método, y me gusta describir la vista de nivel superior en lugar de simplemente args / return value. Tengo especial cuidado en describir cualquier "no linealidad" en la función (límites, casos de esquina, etc.) que podría hacer tropezar a los incautos.
Normalmente, no hago ningún comentario dentro de un método, excepto para marcar elementos "FIXME", o muy ocasionalmente algún tipo de "aquí hay monstruos" que parece que no puedo limpiar, pero trabajo mucho para evitarlos. Como dice Fowler en Refactoring , los comentarios tienden a indicar un código pequeño.
La mayoría de las veces me parece que el mejor comentario es la función o el nombre del método en el que estoy actualmente codificando. Todos los demás comentarios (excepto los que mencionó su amigo, estoy de acuerdo con ellos) me parecen superfluos.
Entonces, en este caso, los comentarios parecen excesivos:
/*
* this function adds two integers
*/
int add(int x, int y)
{
// add x to y and return it
return x + y;
}
porque el código es autodescriptivo. No es necesario comentar este tipo de cosas ya que el nombre de la función indica claramente lo que hace y la declaración de devolución también es bastante clara. Se sorprendería de lo claro que se convierte su código cuando lo descompone en pequeñas funciones como esta.
Los comentarios son parte de una caja de herramientas de programadores y pueden usarse y abusarse por igual. No depende de usted, ese otro programador, o alguien realmente que le diga que una herramienta es mala en general. Hay lugares y horarios para todo, incluidos los comentarios.
Estoy de acuerdo con la mayoría de lo que se ha dicho aquí, ese código debe escribirse tan claro que sea autodescriptivo y, por lo tanto, no se necesitan comentarios, pero a veces eso entra en conflicto con la mejor / óptima implementación, aunque eso probablemente podría resolverse con un método apropiadamente nombrado.
Los comentarios son parte del código, al igual que las funciones, variables y todo lo demás, y si se cambia la funcionalidad relacionada, el comentario también debe actualizarse (al igual que las llamadas a funciones deben cambiar si los argumentos de la función cambian).
En general, cuando programe debe hacer las cosas una sola vez en un solo lugar.
Por lo tanto, si lo que hace el código se explica por nomenclatura clara, no se necesitan comentarios, y este es siempre el objetivo, es la manera más simple y más limpia.
Sin embargo, si se necesita una explicación adicional, agregaré un comentario, con el prefijo INFO, NOTE y similares ...
Una INFO: comentario es para información general si alguien no está familiarizado con esta área.
A NOTA: el comentario es alertar sobre una rareza potencial, como una regla / implementación comercial extraña.
Si específicamente no quiero que las personas toquen el código, podría agregar una ADVERTENCIA: o un prefijo similar.
Lo que no uso, y me opongo específicamente, son los comentarios al estilo de registro de cambios, ya sea en línea o en la cabecera del archivo, ¡estos comentarios pertenecen al software de control de versiones, no al código fuente!
Mi única regla real es que los comentarios deberían explicar por qué el código está allí, no lo que está haciendo o cómo lo está haciendo. Esas cosas pueden cambiar, y si lo hacen, los comentarios deben mantenerse. El objetivo del código existe en primer lugar no debe cambiar.
Muy, muy raramente, comento. MI teoría es que si tienes que comentar es porque no estás haciendo las cosas de la mejor manera posible. Como un "problema" es lo único que comentaría. Porque a menudo no tienen sentido, pero hay una razón por la que lo haces, así que debes explicarlo.
Los comentarios son un síntoma del código IMO sub-par. Soy un firme creyente en el código de auto documentación. La mayor parte de mi trabajo puede traducirse fácilmente, incluso por un profano, debido a los nombres descriptivos de las variables, la forma simple y los métodos precisos y muchos (IOW no tiene métodos que hagan 5 cosas diferentes).
Necesita documentación (de alguna forma, no siempre comentarios) para una comprensión local del código. El código en sí mismo le dice lo que hace, si lo lee todo y puede tenerlo en cuenta. (Más sobre esto a continuación.) Los comentarios son los mejores para la documentación informal o semiformal.
Mucha gente dice que los comentarios son un olor a código, reemplazables por refactorización, mejores nombres y pruebas. Si bien esto es cierto de los malos comentarios (que son legión), es fácil saltar a la conclusión de que siempre es así, y aleluya, no más comentarios. Esto pone toda la carga de la documentación local, creo que en demasiadas cosas, en los nombramientos y las pruebas.
Documente el contrato de cada función y, para cada tipo de objeto, lo que representa y cualquier restricción sobre una representación válida (técnicamente, la función de abstracción y la representación invariante ). Utilice documentación ejecutable y comprobable donde sea práctico (doctests, pruebas unitarias, aserciones), pero también escriba comentarios cortos que proporcionen la esencia útil. (Cuando las pruebas toman la forma de ejemplos, están incompletas, donde están completos, contratos precisos, pueden ser tanto trabajo como el código mismo). Escribe comentarios de alto nivel para cada módulo y cada proyecto; estos pueden explicar convenciones que mantienen todos sus otros comentarios (y código) cortos. (Esto es compatible con la denominación como documentación: con las convenciones establecidas y un lugar en el que podemos esperar encontrar sutilezas, podemos confiar más a menudo en que los nombres cuentan todo lo que necesitamos saber). Los Javadocs más largos, estilizados e irritablemente redundantes tienen su usos, pero ayudó a generar la reacción.
(Por ejemplo, esto:
Realice una n-fold frobulation.
@param n el número de veces para frobulate
@param x la coordenada x del centro de la frobulación
@param y la coordenada y del centro de la frobulación
@param z la coordenada z del centro de la frobulación
podría ser como "Fracticar n veces alrededor del centro (x, y, z)". Los comentarios no tienen por qué ser una tarea ardua para leer y escribir.)
No siempre hago lo que digo aquí; depende de cuánto valoro el código y quién espero que lo lea. Pero aprender a escribir de esta manera me convirtió en un mejor programador, incluso cuando se trata de cortar esquinas.
De regreso al reclamo que documentamos por el bien de la comprensión local: ¿qué hace esta función?
def is_even(n): return is_odd(n-1)
¿Pruebas si un entero es par? Si is_odd() prueba si un entero es impar, entonces sí, eso funciona. Supongamos que tenemos esto:
def is_odd(n): return is_even(n-1)
El mismo razonamiento dice que is_odd() prueba si un entero es impar. Júntelos, por supuesto, y ninguno funciona, aunque cada uno funciona si el otro lo hace. Cámbielo un poco y tendremos un código que sí funciona, pero solo para números naturales, mientras todavía parece que funciona localmente para enteros. En microcosmos, así es como es la comprensión de una base de código: rastreando las dependencias en círculos para tratar de aplicar supuestos de ingeniería inversa, el autor podría haber explicado en una o dos líneas si se hubieran molestado. Odio el gasto de los codificadores espirituales sin sentido que me han puesto de esta manera en las últimas dos décadas: oh, este método parece que tiene el efecto secundario de farbuttling el Warpcore ... siempre? Bueno, si los crobuncles impares se desaturan, al menos; ¿ellos? Revise mejor todo el código de manejo de crobuncle ... que planteará sus propios desafíos para la comprensión. Una buena documentación corta este O (n) puntero persiguiendo a O (1): por ejemplo, conocer el contrato de una función y los contratos de las cosas que utiliza explícitamente, el código de la función debe tener sentido sin más conocimiento del sistema. (Aquí, los contratos que dicen is_even() y is_odd() funcionan en números naturales nos dicen que ambas funciones deben probar n==0 ).
No creo que importe cuántos o cuántos comentarios contiene su código. Si su código contiene comentarios, tienen que mantenerse, al igual que el resto de su código.
EDITAR: Eso sonó un tanto pomposo, pero creo que demasiadas personas olvidan que incluso los nombres de las variables, o las estructuras que usamos en el código, son simplemente "etiquetas", solo tienen significado para nosotros, porque nuestros cerebros vea una cadena de caracteres como customerNumber y entienda que es un número de cliente. Y si bien es cierto que los comentarios carecen de "cumplimiento" por parte del compilador, no están tan alejados. Están destinados a transmitir el significado a otra persona, un programador humano que está leyendo el texto del programa.
Prefiero usar comentarios tipo "Hansel y Gretel"; pequeñas notas en el código sobre por qué lo estoy haciendo de esta manera , o por qué de alguna otra manera no es apropiado . La próxima persona que visite este código probablemente necesite esta información, y la mayoría de las veces, esa persona será yo.
Si bien estoy de acuerdo con que el código debe ser legible por sí mismo, aún veo mucho valor al agregar bloques de comentarios extensos para explicar las decisiones de diseño. Por ejemplo, "Hice xyz en lugar de la práctica común de abc debido a esta cueva ..." con una URL para un informe de error o algo así.
Intento verlo así: si estoy muerta y me he ido y alguien recién salido de la universidad tiene que arreglar un error aquí, ¿qué van a necesitar saber?
Siempre me ha gustado el comentario de Refactoring al comentar:
La razón por la que mencionamos los comentarios aquí es que los comentarios a menudo se usan como desodorante. Es sorprendente la frecuencia con la que observa el código grueso comentado y observa que los comentarios están ahí porque el código es malo.
Los comentarios nos llevan a un código incorrecto que tiene todos los olores podridos que hemos discutido en el resto de este capítulo. Nuestra primera acción es eliminar los malos olores refactorizando. Cuando terminamos, a menudo encontramos que los comentarios son superfluos.
Por controvertido que sea, suena cierto para el código que he leído. Para ser justos, Fowler no dice que nunca comentes, sino que piense sobre el estado de tu código antes que tú.
También me suscribo en general a la idea del código de auto-documentación, por lo que creo que su amigo desarrollador brinda buenos consejos, y no lo repetiré, pero definitivamente hay muchas situaciones en las que los comentarios son necesarios.
Muchas veces creo que se reduce a cuán cerca está la implementación de los tipos de abstracciones ordinarias o sencillas con las que los lectores de códigos en el futuro se sentirán cómodos o, en términos más generales, hasta qué punto el código cuenta la historia completa. Esto dará como resultado más o menos comentarios dependiendo del tipo de lenguaje de programación y proyecto.
Entonces, por ejemplo, si estuviera usando algún tipo de aritmética de puntero estilo C en un bloque de código C # inseguro, no debería esperar que los programadores C # cambien fácilmente de la lectura de código C # (que probablemente sea más declarativa o al menos menos sobre menor manipulación del puntero de nivel) para poder entender lo que su código inseguro está haciendo.
Otro ejemplo es cuando necesita hacer algún trabajo derivando o investigando un algoritmo o ecuación o algo que no va a terminar en su código, pero será necesario entender si alguien necesita modificar su código de manera significativa. Debe documentar esto en alguna parte y tener al menos una referencia directamente en la sección de códigos relevantes ayudará mucho.
el propósito de los comentarios es explicar el contexto: la razón del código; esto, el programador no puede saber por simple inspección de código. Por ejemplo:
strangeSingleton.MoveLeft(1.06);
badlyNamedGroup.Ignite();
¿Quién sabe para qué diablos es esto? pero con un simple comentario, todo se revela:
//when under attack, sidestep and retaliate with rocket bundles
strangeSingleton.MoveLeft(1.06);
badlyNamedGroup.Ignite();
en serio, los comentarios son para el por qué , no el cómo , a menos que el cómo sea poco intuitivo.
Si el código no está claro sin comentarios, primero haga que el código sea una declaración de intenciones más clara, luego solo agregue comentarios según sea necesario.
Los comentarios tienen su lugar, pero principalmente para los casos donde el código es inevitablemente sutil o complejo (la complejidad inherente se debe a la naturaleza del problema que se está resolviendo, no debido a la pereza o el pensamiento confuso por parte del programador).
Requerir comentarios y "medir la productividad" en líneas de código puede llevar a basura como:
/*****
*
* Increase the value of variable i,
* but only up to the value of variable j.
*
*****/
if (i < j) {
++i;
} else {
i = j;
}
en lugar de lo sucinto (y claro para el programador apropiadamente habilidoso):
i = Math.min(j, i + 1);
YMMV
Mi acercamiento:
Los comentarios cierran la brecha entre el contexto / mundo real y el código. Por lo tanto, se comentan todas y cada una de las líneas, en el idioma inglés correcto.
YO DOY un código que no observa esta regla en el sentido más estricto posible.
Uso de XML bien formateado: los comentarios son evidentes.
Sloppy commenting significa código descuidado!
Así es como escribí el código:
if (hotel.isFull()) {
print("We''re fully booked");
} else {
Guest guest = promptGuest();
hotel.checkIn(guest);
}
Aquí hay algunos comentarios que podría escribir para ese código:
// if hotel is full, refuse checkin, otherwise
// prompt the user for the guest info, and check in the guest.
Si su código se lee como una prosa, no tiene sentido escribir comentarios que simplemente repiten lo que el código lee desde el procesamiento mental necesario para leer el código y los comentarios serían casi iguales; y si primero lees los comentarios, también necesitarás leer el código.
Por otro lado, hay situaciones en las que es imposible o extremadamente difícil hacer que el código se vea como una prosa; ahí es donde el comentario podría parchear.
Cuando programe en C, usaré comentarios de varias líneas en archivos de encabezado para describir la API, por ejemplo, parámetros y valor de retorno de funciones, macros de configuración, etc.
En los archivos fuente, me atengo a los comentarios de una sola línea que explican el propósito de fragmentos de código no evidentes o para subdividir una función que no se puede refactorizar a las más pequeñas de una manera sensata. Aquí hay un ejemplo de mi estilo de comentarios en los archivos fuente.
Si alguna vez necesitas más que unas pocas líneas de comentarios para explicar qué hace un fragmento de código, debes considerar seriamente si lo que estás haciendo no se puede hacer de una mejor manera ...