intellij - java documentation 8

Comentando el código (16)

Comenzaría con un estándar para comentar todas las clases (nombre de archivo, etiquetas de control de versión para versión dinámica / último autor / historial de revisión, propósito de clase) y métodos (usos, params, valores de retorno) y asegurar que todas las clases y métodos estén documentados en acuerdo con estos estándares.

Posible duplicado:
¿Comenta tu código?

¿Cuáles son los diferentes estándares y prácticas de la documentación del código y cuáles han funcionado mejor para usted?

Lo pregunto porque mi amigo y yo estamos empezando una empresa y probablemente tendremos que tener un estándar acordado para comentar las cosas, de modo que podamos leer el código del otro más fácilmente.

Como han dicho otros, el código debe ser autocomunicador, por lo que los nombres, eventos y objetos deberían reflejar y leer lo más fácilmente posible lo que están tratando de lograr.

Aparte de eso, los comentarios adicionales se deben usar cuando algo necesita una explicación más detallada, como por qué se realizó un error (esta fórmula y los valores se eligieron por x, referirse a error, etc.).

(Si esto es .NET y también desea proporcionar un archivo de ayuda de Windows, también puede ver Ghostdoc y los comentarios que proporciona, y Sandcastle [un generador de archivos de ayuda de Windows que tomará comentarios sobre código xml y creará un archivo de ayuda de su API]. )

Pero, en general, la regla general es que el 99% del tiempo el código debe ser legible, lógico y desglosarse en métodos que tengan sentido para que no necesite nada aparte del código, y luego los comentarios son solo para completar los espacios en blanco sobre lo que realmente se necesita explicar más.

Depende del idioma, por supuesto, pero generalmente un comentario para cada método que describe lo que hace, lo que requiere para la entrada y produce para la salida son estándar. También puede agregar el nombre y la fecha del autor si lo desea, pero lo más probable es que sea evidente en su aplicación de control de versiones.

En cuanto a otros comentarios, úselos con moderación y asegúrese de describir el por qué, no el cómo, al documentar líneas de código específicas.

Esto es lo que hago. Primero comento las clases y los métodos en el encabezado con Doxygen , esto ayuda, ya que trabajo con Java en casa y con C ++ en el trabajo, aunque si estás usando algo de .net probablemente usarás el hash de Microsofts.

Para los comentarios en línea, prefiero comentar bloques de código: esto es lo que hace el siguiente bloque de código (o debería hacer). No comentes una sola línea, ya que no tiene sentido y a menudo no es útil. Las excepciones a esto se producen cuando se realiza una solución cuando la implementación del lenguaje tiene un error; esto es útil cuando se trabaja con VC6.

Mire lo que los "oficiales" de lenguaje recomiendan. Seguiría eso porque es probable que quien sea que trabajes en el futuro también lo haya escuchado o incluso lo use. Evitaría "inventar" tu propio estándar por todos los medios.

Presiono los comentarios de encabezado de función, pero solo solicito comentarios intrafuncionales cuando son absolutamente necesarios para describir, por ejemplo, una solución para un error de API o alguna otra técnica esencial pero no obvia.

Los comentarios del encabezado deberían:

Describe a qué propósito está destinada la función.
Describe el propósito de cualquier parámetro.
Describe el propósito del valor de retorno.

También se pueden incluir otros comentarios, notas o ejemplos de uso, pero no son obligatorios.

Y sí, los comentarios pueden volverse inexactos y se vuelven imprecisos. No se puede escapar de esto, pero tampoco hay razón para tirar al bebé con el agua del baño. Cuando es correcto, los comentarios pueden ahorrarle mucho tiempo al explorar el código tratando de descubrir su propósito. Confíe en los comentarios, pero verifique, y tómese un minuto para corregir las imprecisiones cuando los encuentre.

Primero y ante todo, los comentarios deben ser claros, concisos, relevantes para el código que están comentando, y proporcionar un valor que no está disponible al leer el código. Por ejemplo, documentando por qué se eligió un algoritmo de hashing en particular sobre los otros disponibles para una función de hash de contraseña.

Si está utilizando uno de los lenguajes basados en .NET, debe usar comentarios XML para miembros públicos y privados, ya que Visual Studio usará esta información para mostrar intellisense para sus clases. También puede usar estos comentarios para generar automáticamente la documentación de API utilizando herramientas como SandCastle. Esto significa que la información debe mantenerse actualizada, pero ese debería ser un porcentaje muy pequeño de tiempo invertido. Si no está utilizando uno de los lenguajes basados en .NET, existen otras herramientas (como Doxygen o Javadoc) que proporcionan comentarios y funcionalidades similares a los comentarios XML.

También debe ser coherente en lo que documenta y cómo documenta. Si coloca un encabezado de archivo, coloque el mismo encabezado en cada archivo (cambiando solo lo que sea necesario, como el nombre del archivo).

Usualmente solo uso estos punteros.

Utilizo "comentarios de encabezado" para documentar funciones, clases, etc. Normalmente esto es más para documentación que para comentarios. Uso C # y Visual Studio y obtienes algunas características agradables cuando usas comentarios XML para esto.

Los comentarios deberían decir por qué hiciste algo y no lo que hiciste. Su código debe ser lo suficientemente claro como para mostrar que, si no es así, cambie el código. Los comentarios que repiten lo que hace el código son tan malos como el código duplicado. Cuando se actualiza el código, los comentarios a veces se olvidan causando más daño que bien.

Los comentarios deben mantenerse al mínimo. Los comentarios son loc''s y deben mantenerse. Así que hazlo sin ellos si puedes

Vale la pena recordar que los comentarios siempre son incorrectos . Esto es particularmente relevante cuando haces cosas como escribir comentarios de encabezado de función grande que enumeran todos los parámetros y el valor de retorno, etc. Puede mantener esto durante mucho tiempo, pero con el tiempo a medida que su base de códigos crezca, los bloques de comentarios se desincronizarán del código real. Cambiará el nombre de un parámetro, o agregará uno nuevo, y olvidará actualizar el comentario. Entonces el comentario es incorrecto, y por lo tanto inútil.

Como han mencionado otros, tus comentarios deberían explicar por qué estás haciendo algo, no lo que estás haciendo. Lo que se puede responder leyendo el código.

Creo que este artículo es relevante. http://www.codinghorror.com/blog/archives/001150.html

El código de autocomentario es un poco falsable en mi opinión. No hay tal cosa. Claro, el código debe ser claro y conciso, pero no se trata de comentarios. Eso es sobre la calidad del código.

Los comentarios, por otro lado, deberían explicar qué problema resuelve el código y por qué. La forma en que funciona el código se entiende leyendo el código mismo; los comentarios deben ser acerca de por qué el código está allí.

En pocas palabras, comente sobre por qué, no cómo. Me doy cuenta de que esto es redundante dadas las otras respuestas, pero no se puede decir lo suficiente.

Escriba su código y comentarios para que sea fácil de leer cuando tenga que regresar en 6 meses y solucionar los errores que estarán allí. Además, si el código está escrito de manera tal que la lógica y la intención sean claras, tenga cuidado con los comentarios excesivos. Esto puede hacer que el código sea difícil de leer. En otras palabras, sé amable con la persona que tiene que mantener el código.

Recomiendo leer Code Complete y la sección sobre cómo comentar allí.

Escogí una convención de comentarios de otro desarrollador cuando estaba en la universidad y me ha sido muy útil a lo largo de los años. Su idea es permitirle escanear a través de un archivo de la manera más rápida y fácil posible, ya sea buscando algo o para obtener una visión general de su estructura. Prefijo cada método o propiedad pública o protegida con la siguiente estructura de comentarios:

/* ====== MethodName ====== */ /// <summary> /// XML comments go here /// </summary> void MethodName()

De todas las convenciones que he visto hasta ahora, esta, al menos para mí, parece ser la forma más clara de hacer que cada método se destaque, y hace que sea más fácil escanear rápidamente un archivo de código fuente. Habiendo dicho eso, odio los comentarios de XML con una venganza debido al desorden visual de los impuestos de paréntesis angulares, y me gustaría que Microsoft se hubiera conformado con algo más parecido a Javadoc o PHPdoc:

/* ====== methodName ====== */ /** * Doc comments go here * * @param A parameter * @returns A number */ int methodName(String param)

Más allá de eso trato de hacer que el código sea autodocumentado como sea posible. Todo método idealmente debería realizar una tarea específica (que por supuesto puede dividirse en subtareas), y su nombre debería describir lo que hace.

¿Qué pasa con los comentarios por el bien de las personas que necesitan escanear el código más tarde para averiguar dónde se rompió o qué puede ser necesario actualizar? Aquí hay un ejemplo que encontré en la web.

http://www.example-code.com/csharp/ssl_async_client.asp

Creo que este ejemplo es bastante bueno si quieres depurar este código. tal vez más "Por qué lo estoy haciendo de esta manera" es necesario, pero no está mal.

Encuentro que gran parte de lo que estoy haciendo es depurar y mantener aplicaciones que son completamente diferentes en la base de código escrita por personas que ya no están disponibles. Para encontrar un error de lo contrario, puede que tenga que leer cada línea de código, parece ineficaz, ¿no?

Me gustaría ver más ejemplos de buenos ejemplos de comentarios que las personas tienen.

En primer lugar, su estándar debe ser que el código no necesita comentarios, debe ser auto-documentado. Como se dijo diferente, los comentarios deberían explicar por qué abordaste un problema de una manera específica.

Personalmente odio los comentarios CS101:

int Count = 0; // initialize Count to zero

Publiqué sobre esto, te hará la vida más fácil si nombras variables y funciones que explican de qué se tratan o qué hacen. Los comentarios, por lo tanto, se deben usar para explicar por qué lo ha codificado de la manera que tiene.