¿Comentarios en código o código autoexplicativo?
!
- Categoría: Trabajar como desarrollador
El gran debate
Ordenar por: Más útiles | Recientes | Cronológico
20 Respuestas
-
!
Karma: 20 (3 votos)
Como siempre se ha dicho, se programa para que otra persona pueda leer el código, y ya que está, que una máquina pueda ejecutarlo.
Yo tiendo a escribir el código lo más autoexplicativo posible. Me gusta comentar las funciones para decir qué parametros recibe, qué hace y qué devuelve.
Pero dentro de los métodos no suelo poner comentarios. Busco el equilibro entre código legible y código optimizado, ya que muchas veces he visto código que han pasado de 3 lineas a 1, pero más complicado que un trabalenguas, y casi siempre el de 3 lineas funcionará igual de rápido y es legible en un sólo vistazo.
Si suelo comentar los fragmentos de código en los que se tengan que pensar mucho, o sea, cuando trabajas con fechas y a X dia, le restas no se cuanto pero también le sumas otra cosa. Vamos, ese código que hará que el lector tenga que sacar una calculadora. Mejor un comentario diciendo qué hace y qué deberíamos esperar de ello.
Así que por norma general, código autoexplicativo y comentar aquellos trozos que por algúna razón no son tan obvios a simple vista. Eso aparte de comentar qué hace cada clases / método.
-
!
Karma: 2.5 (1 voto)
Yo diria que un buen comentario (ojo bien hecho), es mejor que código auto explicativo por que dependiendo del estado de animo de la gente te encuentras.
-
!
Karma: 25 (2 votos)
Yo creo que debe haber un equilibrio entre ambas, teniendo un código legible a primera vista, pero explicado en profundidad en los comentarios.
-
!
Karma: 17.5 (4 votos)
En primer lugar hay que dejar claro que, el código es para las máquinas y los comentarios para las personas. EN GENERAL, quien escriba “código autoexplicativo” no hará bien ninguna de las dos cosas (escribir buen código para las máquinas y dejarlo bien explicado para las personas).
Dicho ésto, la pregunta es taaaaaan amplia y puede aplicar a taaaantos contextos, que comentar las particularidades resulta imposible (no es lo mismo un código en ASM que otro en COBOL, no es lo mismo codificar una actualización de datos en una bd que un algoritmo A* aplicado a un caso particular, etc…).
-
!
Por ejemplo, ¿alguien se anima a modificar la siguiente solución a un problema para que sea “autoexplicativo”? XD XD
-
!
1. Seguro que llamar X, N, Z, D y S a las variables no ayuda mucho (por no decir NADA al entendimiento del programa). Si son lados, en lugar de llamarla X, se podría poner “lado”. Utilizar bien los nombres es esencial.
2. No se utilizan constantes (por ejemplo, el 4 está puesto a pelo, podrías poner el significado de ese 4 en lugar de 4), ejemplo:
if (poliza[x].equal(Constantes.RENOVADA) {
...3. Por convención, normalmente a las funciones se les escribe unos comentarios como cabecera para facilitar la interpretación de posibles llamadas y reutilización de código, ejemplo:
/* $numeroA Integer primer parámetro para realizar la suma * $numeroB Integer segundo número utilizado para realizar la suma. * @return $resultado suma del parámetro $numeroA y $numeroB. */
public function sumarNumeros ($numeroA, $numeroB) {
... return $resultado;
}NOTA.(Es un ejemplo chorra para mostrar como comentar funciones, si se quiere hacer bien, el parámetro de entrada debería ser un array con una lista de números para sumar).
4. Por último, en esta parte: if( z <= d + l ), intenta que cuando vayas a realizar estas operaciones que para cualquiera significa 0, utiliza lo siguiente:
// vamos a comprobar que …
if (lado <= constantes.PERIMETRO + 1)Si viene una persona nueva y le toca modificar tu código, esto es muchísimo más legible.
Nota: Es un workaround, no son los datos reales, simplemente era para explicar como mejorar la comprensión del código.
Espero que ayude.
-
!
Peter, todas las “mejoras” que has comentado ¡sólo agravan el problema! (en ese ejemplo), precisamente he puesto ese ejemplo, porque el tipo de “comentarios” y “buenas prácticas” que indicas NO APORTAN NADA al entendimiento del código.
Únicamente una explicación “al uso”, es decir, un buen comentario PARA PERSONAS, hará que otro lo comprenda (el comentario en ese problema que explica como se llega a esa solución).
Cuando en el cole te dicen que
x =b +Raíz( b^2 – 4ac) / 2a¿Crees que lo entenderás mejor si le ponen “bonitos nombres” a las variables y unas “bonitas constantes” para 2 y 4?.
Los “nombres bonitos” están bien para definir interfaces (en el sentido más amplio de la palabra) que serán usados fuera del código, pero EN EL CODIGO, no siempre poner “menor_valor_posible” que “mvp” hará el código más legible.
Precisamente por eso, yo no he indicado si sí o no, únicamente algo que todo programador debería hacer:
1. asegurar la eficiencia técnica del código escrito.
2. en lo posible y siempre que no afecte a [1], facilitar la lectura del mismo (usando las recomendaciones habituales).
En general, no es una cuestión de todo o nada, sino un problema de optimización de dos variables. Excepto en códigos triviales, habrá que hacer una elección entre código eficiente pero críptico o menos eficiente pero fácilmente entendible.
Por ejemplo, el algoritmo trivial para decidir 3SAT es muy fácil de entender por cualquiera ¡pero es muy deficiente!, los mejores (o menos malos) algoritmos para resolver 3SAT son tremendamente complejos.
Obviamente éste (3SAT) es un caso extremo, pero eso es a lo que me refiero.
Si sólo hablamos de aplicaciones (código) “chorrón” de leer cuatro campos de la base de datos y mostrarlos en un form pues vale, pero entiendo que la pregunta se refiere a CUALQUIER TIPO DE CÓDIGO.
-
!
Pues la verdad es que sí lo entiendo mucho mejor. Vamos pero eso de hacer Hard-coding creo que no es un buen principio para seguir. Te lo pongo de la wikipedia por ponerte uno de muchos: http://es.wikipedia.org/wiki/Hard_code
Usar un código elegante y descriptivo es SIEMPRE una garantía de saber programar bien, pero sobre todo es garantía de que si alguien tiene que modificar algo y no sabe hacer ese problema y le dices que ahora en lugar de tener 4 lados tiene 5, Si ve una constante llamada LADOS, lo cambia y funcionando. De tu forma, tiene que ir por cada uno de los 4 y si lo utilizas para otra funcionalidad daría un error.
A eso se le llama hacer las cosas bien Jose Juan y no una chapuza que solo la entiendes tu.
-
!
Peter, ¿dices que “hard-codeo” en ese ejemplo?, ¿a qué constante exactamente debería darle un nombre?.
Seguramente recordarás (porque se que lo has disfrutado):
“Some constants are so easy to recognize that they don’t always need a named constant to hide behind so long as they are used in conjunction with very self-explanatory code.”
Si incluso la cifra 5280.0, NO REQUIERE ser etiquetada como constante (según las buenas prácticas) ¿cómo lo va a requerir el número 4 ¡que identifica los cuatro lados de un cuadrado!?.
-
!
lamejor
Karma: 250 (22 votos)
Pues a ver, ¿Quieres más a papá o a mamá?
Está claro que ambas cosas son compatibles y, sobre todo, necesarias.
A mí no me vale de nada un código con variables k, i, j, mmn, que las entiende quien lo programó y poco más. Pero tampoco me vale un código sin un comentario. No digo ya entrar en puretismos de JavaDoc 100%, pero no pasa nada por comentar al menos los procesos principales y más complejos. No voy a comentar un getter, pero si una función tiene 100 líneas y llama a DAOs, clases varias etc… unos comentarios vienen de vicio.
Luego tenemos la vertiente de los que defienden que con hacer TDD ya no hace falta comentar nada. Nuevamente nos equivocamos pensando que son cosas excluyentes. Está bien TDD, muchas veces reduce el código, también se puede poner comentarios en los tests (es gratis!). Pero lo cortés no quita lo valiente.
Conclusión: – Comentarios en código? Sí, pero los necesarios, no hay que comentar todo todo todo. – Código autoexplicativo? Sí, siempre.
-
!
Totalmente de acuerdo con lo que has dicho. Comentarios los justos.
-
!
Lo más seguro es que si una función tiene 100 líneas hace falta una buena refactorización en vez de tanto comentario :P
-
!
Totalmente de acuerdo. Yo suelo migrar de vez en cuando programas antiguos y algunas veces llega a ser un infierno, precisamente porque o no tiene comentarios, o las variables son abstractas o directamente ambas cosas.
Un saludo y gran respuesta!! -
!
Comparto, en mayor o menor medida tu comentario, pero… Cuando dices: “Está bien TDD..., muchas veces reduce el código, “
No se puede estar más equivocado, la única forma de reducir el código es ¡escribiendo menos código! Una de las basas que usan los retractores de TDD es precisamente esa, que muchas veces se escriben más tests de la cuenta (aunque, supuestamente, escribas las funcionalidades que necesitas).
PD: Los tests también son código.
PD2: No soy retractor de TDD. -
!
Totalmente de acuerdo, sería imposible negar los aportes que cada uno brinda para ayudar a comprender el código, especialmente cuando fue escrito por alguien mas.
-
!
Karma: 5 (0 votos)
el nombre de la función debiera ser nemotecnico y autoexplicativo, desde ese punto los comentarios incluso sobran, pero si usan algun sistema de documentación, como phpdocumentator o el equivalente en tu lenguaje favorito, seria bueno documentar la sintaxis y algún ejemplo de uso para cada método y clase
-
!
brillante
Karma: 130 (11 votos)
Como dijo un gran filosofo: “Si fue difícil de implementar, tiene que ser difícil de entender”.
Este filósofo también es creador de frases míticas como “Las cosas se prueban en producción” y “¿Para qué quieres una base de datos de desarrollo?”
-
!
brillante
Karma: 62.5 (6 votos)
Los comentarios son fundamentales siempre, sin excepción. Lo que hoy estás haciendo, esos nombres que mientras desarrollas te parecen super identificativos, mañana, pasado o cuando te toque mantener ese código, más, si lo tiene que mantener algún compañero, serán completos extraños. A esas soluciones a las que llegaste, que en su momento eran clarísimas, pueden no serlo tanto, días después, cuando no tienes tan frescos los entresijos de la aplicación. Ahí entran los comentarios. No vas a explicar lo que hace un for, pero un buen comentario te puede librar de días de vagar por el desierto.
-
!
Karma: 2.5 (3 votos)
Eso depende de para que lo uses, si vas a crear una aplicación con varias personas y sabéis de que va la historia puede que con unas pautas básicas os entendáis.
Pero si se va a distribuir un código creo que habría que realizar ambas cosas, comentar el funcionamiento del código y que esté bien estructurado y organizado para que cualquiera pueda entenderlo.
-
!
El problema, por muchas pautas que pongas, al cabo del tiempo, si tienes que volver a tocar el proyecto o simplemente retocar algo que hiciste al principio y que ahora ha cambiado, puede que ya no recuerdes nada de los parámetros de esa función y al no haber puesto comentarios, tengas que perder mucho más tiempo de acordarte de como lo hiciste, que es lo que hace y eso que si hubieras perdido el tiempo poniendo un simple comentario ;)
-
!
Karma: 5 (0 votos)
El código tiene que ser autoexplicativo y la cantidad de comentarios a introducir depende de quien esperes que vaya a leer tu código.
Por ejemplo, en un proyecto web no vas a documentar prácticamente nada de lo relacionado con protocolos, pero si por casualidad tuvieras que escribir opengl dentro de un proyeto web documentarías hasta el más mínimo detalle, y vicerversa, a menos que supieras que quien va mirar el código detrás de ti ya domina las dos tecnologías, en cuyo caso no haría falta documentar practicamente nada. -
!
Karma: 20 (1 voto)
no comments for you, it was hard to write, so it should be hard to read
-
!
Karma: 7.5 (1 voto)
¿Comentarios, autoexplicativo?
Los programadores de verdad graban el código en binario directo sobre el disco duro con cincel y martillo.Bueno ya en serio, ¿Porqué elegir uno cuando se puede tener ambos? Por otra parte un pequeño README puede ahorrar mucho tiempo a la hora de entender el código.
En lo personal me gusta mucho el código autoexplicativo, pero cuando hay métodos que tenemos se usan de forma excesivamente común ¿Quién no prefiere un “shortcut” en lugar de una larga semántica?
-
!
Karma: 5 (0 votos)
Todo depende de la seccion del codigo. Normalmente los comentarios que pongo son: “En esta parte tengo que calcular el porcentaje de comision basado en las ventas realizadas en el periodo”. Y basta, si le puedo poner una formulita, listo… No mas, a buen entendedor pocas palabras… Y si, las verdaderas pruebas son en producción.
-
!
Karma: 10 (0 votos)
Bueno, mi aportación: estoy hasta el gorro de ver comentarios como éste en código:
- Me creo un objeto albarán y otro pedido
Código…
20 líneas (sin comentarios)
Fin_código¿De qué me sirve a mí ese comentario? De nada. ¿No sería mejor haber explicado POR QUÉ creas esos dos objetos en concreto? La gente tiende a comentar cosas banales y a no explicar porqué se hizo así y no de otra manera, que es lo importante bajo mi punto de vista.
-
!
Dime donde trabajas, mas que nada por que a ti el análisis te lo dan antes que el código. ;)
-
!
Karma: 5 (0 votos)
No veo que tenga sentido comentar lo que hace un trozo de código (ejemplo: clase “Circulo” método “area”) Sin embargo lo interesante es comentar por qué.
-
!
Karma: 5 (0 votos)
Cuando llevas horas programando se entiende mucho mas un codigo autoexplicativo que un comentario en lenguaje natural
-
!
Karma: 5 (0 votos)
Bueno, yo soy nuevo aqui, aunque tengo ya tiempo leyendo los articulos de esta pagina, y me parecio buena idea participar en esta pregunta, yo en lo personal aun soy estudihambre, es decir, no he trabajado en el ambito del desarrollo de software, pero creo yo, que por muy buen programador que seamos, al paso del tiempo tendemos a olvidar las cosas, asi que a mi en lo personal me gusta comentar el código por que si es que tenemos un error, esto nos ayuda a saber de forma mas precisa en donde esta, ademas que si quisieramos hacer alguna modificacion o agregar algo, sabriamos donde hacerlo sin tener que echar un vistazo a todo el codigo, y bueno ese es mi punto de vista, porque yo pienso que si a veces tomar el codigo asi nomas de un programita de escuela en ocaciones es confuso, no puedo ni imaginarme confuso que seria tomar un proyecto mas formal sin comentarios o documentacion.
-
!
Karma: 20 (1 voto)
Recomiendo leer el capitulo dedicado a los comentarios en el libro “Clean Code” (recientemente traducido como “Código limpio”),
Si quedan dudas volver a leerlo. -
!
Karma: 5 (0 votos)
En general creo que un código cuyas funciones, variables, etc. se expliquen por sí solas no necesita demasiados comentarios, parte su calidad como software
es precisamente esto. Lo cierto es que no siempre es fácil encontrar las definiciones adecuadas y entonces comentar se vuelve necesario.
Yo siempre llevo en mente aquello que reza:“Programa siempre como si el tipo que acabe manteniendo tu código fuera un psicópata violento que sabe dónde vives.” — Martin Golding. -
!
Karma: 5 (0 votos)
Solo NO pondría comentarios si estuviese seguro de que es un único archivo que nunca va a ser leído por otras personas y que funciona tan eficientemente bien en lo que hace que nunca deberé codificarlo. Puede sonar imposible pero se llega a creer en eso para 1 archivo cada mes.
