¿Escribir comentarios dentro de los métodos no es una buena práctica? [duplicar]

Tu amigo está equivocado, y muy pocos programadores estarían de acuerdo con él. Debes escribir comentarios cuando y donde sientas que es mejor que te ayuden a comprender.

Ignora a tu amigo. Comenta según sea necesario. Pero intente hacer que su código se explique por sí mismo, de modo que los comentarios no sean necesarios . Recuerde que su computadora no está ejecutando comentarios, por lo que es fácil que los comentarios no estén sincronizados con lo que realmente está sucediendo.

Tiendo a usar un bloque de comentarios para explicar un poco de lógica particularmente delicada, que de otra manera tomaría un poco de dificultad mental para leer. Y luego intentaré aclarar la lógica y eliminar la necesidad de explicación.

El código bueno es auto-documentado. Un método debe hacer exactamente una cosa, y esa cosa debe ser obvia por el nombre del método y las especificaciones del comentario. Por lo tanto, la necesidad de comentarios en el método que explica la lógica sugiere que el método debe dividirse en métodos de responsabilidad única.

Ahora, por la realidad. Te enfrentas a un complejo código de código de espagueti y tratas de ser amable con los mantenedores. No tienes el tiempo o el mandato para refactorizar 8 millones de líneas de código, e incluso si lo tuvieras, habría matices porque todo es complejo. ¿Qué haces?

Me sorprende la cantidad de personas que no están de acuerdo con esta opinión.

1. El buen código debe ser autodocumentado, por lo que debe elegir cuidadosamente los nombres de los métodos, los nombres de las variables, etc.
2. Su método no debe ser tan largo como para que no pueda ver el método completo y los comentarios en una pantalla

Dicho esto, hay excepciones. Pero son excepciones. Y el punto con sus excepciones, es que son pocos en números. Realmente solo necesitas explicar el código en línea si estás haciendo algo contraintuitivo.

Una situación típica en la que podría necesitar comentarios en su método es cuando aplica un truco local para optimizar la velocidad, pero que en la primera lectura podría darle a otro programador un momento de wtf. Ese es un buen punto para agregar un comentario.

Pero en general: no, no agregue comentarios en sus métodos.

Creo que está hablando de un caso como este:

public void upload() {
    // destination host
    String host = ....
}

Donde podría mejorar el código teniendo un nombre de variable más explícito, en lugar del comentario:

public void upload() {
    String destinationHost = ....
}

Creo que su amigo se refiere al "Código limpio" de Robert C. Martin. Sin embargo, creo que está simplificando demasiado la situación. El libro habla de dar a los métodos nombres claros y descriptivos, que todos deberíamos saber, pero que nunca se pueden repetir lo suficiente. El libro también recomienda hacer métodos muy pequeños envolviendo cualquier bloque de código que pueda recibir un nombre claro y descriptivo en un método propio. Por lo tanto, si cree que un bloque de código necesita un comentario que explique lo que hace, entonces debe hacerlo un método separado con un nombre apropiado. En teoría, si todos sus métodos están por debajo de 5 líneas y si todos tienen buenos nombres descriptivos, debería ser obvio lo que hacen sin tener que explicarlo en un comentario.

Sin embargo, no significa que nunca debas tener comentarios dentro de tus métodos. El punto es que los comentarios no deben ser redundantes. Deberían agregar información. Si tiene un método que hace exactamente una cosa, y esa cosa es obvia por su nombre, entonces no necesita un comentario que explique lo que hace. Sin embargo, tiene mucho sentido tener un comentario que explique por qué lo hace de esa manera en particular. Es posible que desee un comentario que explique por qué eligió un algoritmo sobre otro, o por qué eligió una estructura de datos sobre otro. En otras palabras, desea que el código en sí explique cómo funciona, y desea que los comentarios expliquen las razones de sus decisiones de diseño, i. mi. por qué las cosas se hacen de esta manera en particular.

El libro recomienda refactorizar código incorrecto en lugar de comentarlo. Esta es ciertamente una gran idea en teoría, pero en realidad puede que no tenga el tiempo o la infraestructura, como un marco de prueba de unidad de trabajo con el conjunto adecuado de pruebas de unidad para hacer eso. Hay momentos en que te enfrentas a una base de código desordenada, en la que debes trabajar ayer, y la única forma de avanzar es tratar de entender las piezas desordenadas y comentarlas como una forma de tomar notas por ti mismo.

Sí, definitivamente escribes comentarios dentro de los métodos en Java.

Como convención de códigos de Sun dice:

  

Los programas Java pueden tener dos tipos de   comentarios: comentarios de implementación y   Documentación de los comentarios. Implementación   Los comentarios son los que se encuentran en C ++, que   están delimitados por /*...*/ y // .   Comentarios de documentación (conocidos como "doc   comentarios ") son solo para Java, y son   delimitado por /**...*/ . Doc comentarios   Se puede extraer a archivos HTML usando   La herramienta javadoc.

Por lo tanto, los comentarios en los métodos son comentarios de implementación.

Estoy totalmente en desacuerdo con tu amigo y sostengo que los comentarios de la función en línea son una parte muy importante para escribir un buen código. Los comentarios de funciones están diseñados para dar a los clientes del código una mejor comprensión de lo que se supone que debe hacer el código, lo que significan sus parámetros y valores de retorno, el tipo de invariantes que espera tener al entrar y salir, etc. Sin embargo, los comentarios en línea están dirigidas principalmente a los mantenedores del código e idealmente como una serie de notas mentales para el autor original del código. Permiten ver un método complejo que otra persona ha leído e intuir lo que pensaba el autor original. También hacen que sea más fácil diagnosticar errores, ya que si los comentarios describen cuál es la intención del código y qué suposiciones están haciendo, puede ser mucho más fácil averiguar cómo un fragmento de código es erróneo cuando se detecta un fallo de funcionamiento.

Personalmente, los comentarios en línea me parecen útiles porque me obligan a probarme a mí mismo que el código que voy a escribir funcionará correctamente. A menudo, me acostumbro a no escribir ningún código sin comentar claramente cuál es la intención y cómo va a funcionar. Más de las veces, esto me impide cometer errores tontos en el código porque descubriré que mi explicación es incorrecta o que no tiene en cuenta algún caso de vanguardia.

Por supuesto, todos tienen su propia disciplina de codificación, y quizás a algunas personas les resulte más fácil escribir código sin comentarios en línea y, en su lugar, dividir el código en múltiples métodos más pequeños. Sin embargo, según mi experiencia, los comentarios en línea son invaluables durante el desarrollo y la depuración, y son extremadamente útiles para otras personas que tienen que revisar y mantener mi código mucho después de que haya pasado a otro proyecto.

Su amigo puede estar expresando la noción de que los comentarios son, si no son un "olor a código", un " desodorante ". Esto no es específico de los comentarios en el método, pero puede ser más cierto para los comentarios en el método que para los comentarios en el preámbulo.

Cuando escribes un comentario, normalmente es para explicar algo. Cuando algo necesita explicación, bueno, no se explica por sí mismo. El gran código es autoexplicativo. Entonces, cuando agrega comentarios, está ocultando su falta de autoexplicación, sin que se explique por sí mismo. Así que cada vez que escribes un comentario como ese, en lugar de cambiando el código (cambiando de nombre, por extracción de método, etc.) para hacerlo se explica por sí mismo, estás no alcanzar el ideal.

Pero todos caemos por debajo de la perfección de vez en cuando. Y a menudo es mejor agregar un comentario explicativo que dejar el código difícil de entender sin documentar.

Al comentar su código (o el código realmente mal documentado de otra persona) a menudo puede enfrentarse a sentimientos de puro disgusto , odio o ira . El código puede comportarse de manera frustrante e inesperada y es posible que tenga que agregar algunos trucos muy malvados para que funcione durante algún plazo.

En todos los casos que expresen sus sentimientos al anotar las partes respectivas del código con algunas palabras complicadas (consulte el linux kernel fuckcount ) es una práctica común. Esos comentarios deben estar dentro de los métodos para que no aparezcan en la API auto-documentada, por lo que ni su jefe ni sus clientes ni ninguna otra persona agnóstica de código fuente lo verán jamás.

Sin embargo, tus compañeros programadores sentirán una gran alivio y felicidad al estudiar la fuente. (Y, por supuesto, puedes agregar notas a ti mismo o usar el código fuente como medio de comunicación hasta cierto punto, #TODO: add more examples here )

Por supuesto, podría argumentar que este tipo de comentarios no deben estar allí en primer lugar, o que deben eliminarse antes de la versión final, pero en estos días los proyectos de software tienen ciclos de publicación muy cortos, y algunos comentarios aún son relevantes muchas compilaciones nocturnas más tarde, por lo que quizás tu amigo debería comenzar a aprender a leer (y escribir) entre las líneas .

Los buenos comentarios explican el por qué no el cómo. Esa es la distinción clave aquí. La mayoría de las personas podrán seguir lo que está haciendo, pero el motivo por el que lo hizo requiere comentarios adicionales. Esos comentarios deben estar lo más cerca posible de la operación.

Es una práctica común que los programadores pongan comentarios dentro de los métodos cuando piensan que no está claro para otros programadores qué está haciendo el código. También los programadores ponen comentarios TODO dentro del método a veces. Sin embargo, es cierto que si tiene demasiados comentarios dentro de los métodos, es posible que deba retroceder y pensar si está haciendo las cosas demasiado complicadas de lo que debería ser. En otras palabras, probablemente desee evitar comentar algo obvio para otros programadores, ya que es más difícil leer el código con ellos.

Para tomar la sugerencia de tus amigos de manera positiva, debes recordar que podemos evitar comentar demasiado al nombrar las variables y los métodos adecuadamente, mantener cada método pequeño y asegurarnos de que no hagan demasiado personal.

Creo que la razón por la que dijo eso es porque cree que las funciones deberían ser lo suficientemente cortas para que cada una encapsule una sola operación conceptual.

No necesariamente me suscribo a esa creencia hasta el extremo (por varios motivos, incluido el hecho de que leer dicho código puede convertirse en una pesadilla), pero si lo hiciera, podría seguir que solo tendrían un comentario por función, ya que solo hay un concepto por función y un comentario por concepto.

De cualquier manera, uso los comentarios cuando y donde sea que haya un código cuya elección o comportamiento no sea inmediatamente obvio, a menudo relacionado con el rendimiento o las matemáticas esotéricas. Ese tipo de cosas a menudo no concierne inmediatamente al consumidor de la función, por lo que diría que en realidad es una buena idea ocultarlo de la documentación.

Creo que su amigo estaba hablando de javadoc, que generará documentación de su comentario si está por encima de su declaración de método (y decorada con un asterisco adicional) como este:

/**
   get a webpage for a given url 
   @param url: the url to get
   @returns String: the http-source 
*/
public String getWebpage (String url) {
... 

Si pones este comentario dentro del método es inútil.

Por lo tanto, como regla general: ponga los comentarios en la fuente Java por encima del método.

Las excepciones pueden y ocurrirán. Estoy de acuerdo en: usar métodos cortos, escribir código de auto-documentación. Sin embargo, javadoc como herramienta fomenta la duplicación de comentarios, porque de lo contrario se ve tan desnudo en la documentación. :)

Concedo el punto de que en un método escrito desde cero, uno podría documentar su función solo dentro del encabezado. Sin embargo.

Encuentro que a menudo se insertan comentarios donde se descubrieron errores y se pasó por alto un matiz sutil incluso si el método solo tiene una única responsabilidad , lo cual, para ser honesto, rara vez es el caso en el código heredado . Además, no veo ninguna razón para tener un nombre de variable que tenga cuarenta caracteres (incluso si solo se usa en dos lugares) cuando un nombre de variable más corto con un comentario breve puede ser más fácilmente digerido y reutilizado más tarde. Limpio y conciso es lo mejor, pero sobre todo, es un medio de comunicación con otros programadores, al igual que los correos electrónicos, las cartas y la poesía. Y a eso agrego la cita:

"Solo he alargado esta carta porque no he tenido tiempo de hacerla más corta".

Blaise Pascal, (1623-1662) Lettres provinciales

Es bueno tener un código que no necesita comentarios. Cuando obtiene, guarda y borra cosas, tenemos una idea bastante buena de lo que está pasando y no necesitamos comentarios.

A veces, el código se vuelve desordenado y es un candidato para refactorización, por lo que es posible que tengas que comentar mientras tanto.

Hoy tuve una línea de código para no hacer lo que se espera. Aparentemente, una tabla de datos .net no cree que una fila que se haya importado sea un nuevo registro. Cuando inserta los registros de la tabla no pasa nada. La fila que se importa debe cambiar su estado primero. Un simple comentario es todo lo que se necesita, así que cuando vuelva a eso dentro de 6 meses y piense: "¿Para qué demonios necesito eso?" Lo sabré.

Los comentarios solo hacen que el código sea más fácil para el programador, recuerde que los comentarios no se ejecutarán.

Si después de algunos meses leería su código, los comentarios facilitarán la lectura del código.

Hará que el código sea mantenible y cualquier otro programador que vea el código encontrará fácil entender la lógica que has implementado.

No significa que siempre tenga que agregar comentarios, incluso para un método con pocas líneas de código.

Como, por ejemplo, el siguiente código se explica por sí mismo y no requiere ningún comentario para dejar clara su función

public String getName(){
    return name;
}

Mientras que cuando un método es grande, agregue comentarios para que sea más legible cada vez que cualquier programador lo vea.

Recuerde que mientras codifica, puede pensar que el código se explica por sí mismo, pero cuando lo vea después de seis meses, los comentarios que agregó hace seis meses definitivamente lo ayudarán a usted o a cualquier otro programador a entender el código rápidamente.

En primer lugar, su pregunta estaba orientada específicamente a Java, lo que influye significativamente en la respuesta.

La cantidad de comentarios que se requiere está altamente relacionada con el idioma en el que estás trabajando.

• Algunos lenguajes como Java y C # se prestan extremadamente bien al concepto de código de auto-documentación. En estos idiomas, es mejor dedicar sus esfuerzos a hacer que el código sea lo más legible y descriptivo posible, y luego agregue comentarios en línea solo para cosas que no puede describir de forma nativa dentro del idioma.

• Algunos lenguajes como SQL son más difíciles de hacer legibles. La sintaxis, el orden de evaluación, el anidamiento, etc. pueden hacer que sea más desafiante diseñar de manera autodocumentada. El mismo enfoque básico sigue siendo válido: concéntrese en usar el lenguaje tanto como sea posible, luego agregue comentarios para compensar las áreas que no son claras o confusas.

En general, no puede abolir el 100% de los comentarios, pero su objetivo debería ser eliminar la necesidad de los comentarios tanto como sea posible haciendo que el código sea más autodescriptivo. Los resultados de estos esfuerzos suelen ser menos código en general y código mejor organizado. Independientemente de si todavía hay comentarios presentes, esto significa que su código será mucho más fácil de mantener y accesible, que es realmente lo que los comentarios pretenden ayudar en cualquier aspecto.

La idea de que Javadoc (o incluso las sugerencias autocompletadas de Delphi) deben cambiar la forma en que una persona codifica (aparte de agregar funcionalidad para javadoc) es bastante absurda.

Pregúntele a su amigo qué vino primero, el javac o javadoc?

Eso es como preguntar qué vino primero, la vaca o la Sra. O'Leary

Además, javadoc debe ser para personas que implementan su clase y funciones, los comentarios en el código son para las personas que mantienen su código. Especialmente con sus métodos privados, nadie debería necesariamente tener que mirar su código para ver qué hace. Para eso son los doc. Pero si alguien necesita modificar algo debido a un error por un error, entonces desea comentarlo en su método.

Obviamente, está asumiendo que el 90% del código, que de hecho es una corrección de errores, es malo. Nunca he leído "El programador pragmático", pero puedo asumir que no hace referencia a ese libro.

Tiraré mis dos centavos ahora que la fiesta ha terminado bastante bien. Utilizo los comentarios cuando describo un poco específico de lógica de negocios o cuando tengo que agregar algo para cubrir un caso imprevisto.

El código evoluciona con el tiempo para dar cuenta de cosas que no se conocían de antemano, y cuando se aplica una curita, en lugar de suponer que se sabe por qué se pone esa curita a veces es útil agregar un pequeño bloque dentro del código que dice "oh, por cierto, tuve que arreglar esto y aquí está la referencia del rastreador de errores para que pueda seguir la conversación" y en mi caso (como uso FogBugz) sería se parece a esto:

//Case: 1234 ~ Throttling based on unusual activity per ABC request.
Throttler myThrottler = new Throttler( oldActivity );

o lo que sea. Así que mi punto es que algo que parece fuera de lugar y no es tan legible es probablemente un buen lugar para el documento en línea. El conocimiento recolectado es una cosa hermosa.

Pero mi primer punto fue mi lógica de negocios. Literalmente, tengo un bloqueo en un procedimiento almacenado que estoy a punto de reescribir esta AM que tiene algunas reglas de negocios en el frente.

/****************************************************************
author  yourstruly
date    2010-11-18
descrip intended use is to blah blah blah
        ended up over actual measured blah blah blah according to blah blah blah
        rules from the customer are:
        If the sum of the blah blah blah is higher than the blah blah blah
        and the blah blah blah contain blah blah blah,
        and the blah blah blah is non-zero,
        recalculate the blah blah blah to fit within the blah blah blah

        Additional rules for us internally: 
        if the blah blah blah originally read blah blah blah don't blah blah blah (set to zero)

        rewritten here with (1) traceable statements for the where clauses.
        If 
            the blah blah blah(1) is higher than the blah blah blah (2)
        and the blah blah blah (3)
        and the blah blah blah is non-zero (9)
        and the blah blah blah is lower than the blah blah blah (4)
        and the edited blah blah blah is higher than the blah blah blah (5)
        then recalculate the blah blah blah (6)
        // See note lower in this document on the math

        If 
            the blah blah blah(1) is higher than the blah blah blah (2)
        and the blah blah blah (3)
        and the blah blah blah is higher than the blah blah blah (7)
        then set the blah blah blah to zero (8)

        (7) dictates the same as (4) but it's easier to do (7)
****************************************************************/

Sorry for the blah blah blah's but proprietary rules and all that ;)

Y de repente ves que tengo requisitos (!) incrustados en mi código como comentarios y puedo referirme a los comentarios como /*(1)*/ (lo que hago) para que esto sea fácilmente rastreable para el siguiente empleado ( lo que era, y pudo encontrar las partes que necesitaban ajustes inmediatamente) y luego, si alguien quiere saber cuál era la especificación, puede leer el comentario de arriba, y si alguien quiere saber qué es el pseudocódigo, ahí está y si alguien quiere convertir el pseudocódigo al código, ahí tienes. Para mí esto es mucho más legible (para mi caso), ya que conserva la solicitud original (cortada del correo electrónico) y permite que el pensamiento se reúna rápidamente sin demasiada reflexión, y permite el uso de transformaciones sencillas del pseudo en código real.

Y sí, hay algunos comentarios en línea que dicen que tal o cual no funcionó como se esperaba en el pseudocódigo porque el requisito no coincidía con los datos, así que tuvimos que ajustar los datos. Pero ese es mi punto. Documentamos en línea los casos de borde, y dejamos el pseudo-código en el código adecuado para seguir la lógica, por lo que todos sabíamos lo que se esperaba de los requisitos originales

El problema con los comentarios en línea es que se deben mantener junto con el código (también es cierto para los comentarios de función / método / módulo / nivel de clase, pero no en gran medida); Dios sabe la cantidad de código fuente que aún existe, donde los comentarios no tienen absolutamente nada que ver con el código que documentan, la OMI es tan mala o peor que no tener ningún comentario.

Lo ideal es que la documentación en línea se limite a las siguientes situaciones:

• Explicando el código que está fuertemente optimizado o "complicado", junto con una justificación de por qué el código está tan fuertemente optimizado o "complicado" ("nos faltaba el requisito de rendimiento X y el perfil mostró el cuello de botella para estar en esta sección; las optimizaciones a continuación obtuvieron un Y% de rendimiento ");

• Haciendo referencia a un estándar o requisito ("DTED 0 espaciado posterior es de 30 segundos de arco");

• Identifique el código que necesita un mayor análisis / desarrollo ("TODO");

Primera ley de la documentación del código: no documente lo obvio. Corolario a la primera ley de documentación de código: escriba un código que sea obvio en la mayor medida posible.

Tu amigo está equivocado.
Su amigo tiene razón parcialmente en que el USUARIO de su método solo debe leer los comentarios de la documentación. Sin embargo, a menos que escriba un código claro e inequívoco, el código limpio que NUNCA deberá modificarse por cualquier motivo (esto significa que los requisitos y las plataformas nunca cambiarán), los comentarios en el cuerpo son muy útiles.

Cuando estoy escribiendo código con un diseño poco claro (esto sucede, no debería, pero sí sucede). A menudo escribiré los comentarios de documentación (lo que debería hacer el método), el bloque de método (Devolver 0, devolver nulo, lanzar No implementado - lo que sea que necesite) y luego escribiré comentarios de implementación como:

//Get Connection String
//Connect to DB !!-- EXCEPTION --!!
//Build Query and Params.
//Parse Query Results
//Return answer

Esto me dará una idea clara de lo que hay que hacer. También le dará a un desarrollador futuro una idea clara de lo que estaba tratando de lograr.

En otras palabras, los comentarios de la documentación son para los usuarios, explicando QUÉ se está haciendo. Los comentarios internos (Comentarios de código) son para desarrolladores, explicando CÓMO se está haciendo.

Gran pregunta.

La respuesta podría ser "depende".

Si puede dividir una parte no clara en un método o función propia, hágalo, y surgirán otros que deben mantener su código y lo llamarán bendecido. Usa los comentarios de Javadoc para aclarar lo que no está claro. Este puede ser el punto principal de tu amigo.

Aquí hay una cita de un texto comp sci que no puedo recordar (y disculpas al autor):

i++; // increment the counter

El punto del autor en el ejemplo es que el comentario es superfluo. Si ha tomado Programación 101, no necesita el comentario.

Si estás haciendo algo que no es muy obvio para los demás (o posiblemente tú mismo dentro de seis semanas), entonces, por supuesto, comenta lo no tan increíblemente obvio.

Por ejemplo, ¿comprendes inmediatamente?

assertFalse("valid status differs", file1.isValid() ^ file2.isValid);

o puede que te ayuden estos comentarios

// Java XOR operator a^b returns true iff a and b differ.
// If file1 and file2 are both isValid, return false.
// The assertion is that the two versions of isValid should be the same.

Incluso si eres excelente con operadores booleanos y usas XOR regularmente, los comentarios deberían ayudarte y acelerar tu comprensión.

O considere este fragmento para convertir una cadena en un int, usando un Número n, sin comentarios:

...
} else {
  Double d = (Double) n;
  Long l = d.longValue(n); 
  int ans = n.intValue(); 
  if (l.equals ((long) ans)) return ans; 
  throw new ParseException("Field too big to be stored as int");
}

Compare con el código comentado:

...
} else {
  // n must be a double
  Double d = (Double) n;
  Long l = d.longValue(n); // l contains the sInt as a long
  int ans = n.intValue(); // was it truncated?
  if (l.equals ((long) ans)) return ans; // not truncated -- they were equal as longs
  throw new ParseException("Field too big to be stored as int");
}

Admitiré fácilmente que este último fragmento está "muy comentado". Creo que los buenos programadores codificarán para ayudar a comunicarse y aclarar. Err en el lado de los comentarios liberales. Siempre puedes eliminarlos más tarde.

Comente cuando sea necesario, no tanto como sea posible.