Constellation Knowledge Network - Aprendizaje de Feng Shui - ¿Cómo escribir buenos comentarios de código?

¿Cómo escribir buenos comentarios de código?

Para los comentarios de código, existen diferentes regulaciones o explicaciones en diferentes tutoriales o principios. Algunos principios requieren que se utilice JavaDoc para describir cada método, mientras que otros principios requieren que cada atributo esté etiquetado y nombrado. Me gustaría creer que cada comentario que parece fuera de lugar tiene algún propósito bien intencionado, y eso es lo que son los comentarios:

Explicar código que no se explica por sí solo.

Cuando trabajamos en código, tendremos más o menos una lógica antigua que no tiene nada que ver con el negocio que se ejecuta en el código. A veces, no es solo el nombre de una variable o el nombre de un método lo que puede explicar claramente el contenido comercial que esperan los estudiantes de producto. Esperamos agregar lógica fuera del código, pero un comentario largo no parece apropiado, por lo que generalmente agrego una restricción al comentario:

Describe el método actual de la manera más concisa posible, lógica que los atributos no pueden explicar.

Entonces las palabras clave en esta restricción son: simplificado, actual e inexplicable. Este es mi entendimiento actual. Si tiene mejores ideas, espero que pueda contactarme para comunicarse. Por supuesto, estas palabras clave también se explicarán más adelante.

El concepto de degradación de código se ha explicado en muchos campos. Una visión más generalizada es que la vida útil de producción de una aplicación puede ser de 3 a 5 años. Por supuesto, hay mucho margen para la definición de inutilizable cuando se acerca la fecha límite. Pero la idea principal de esta declaración es: con el desarrollo iterativo del negocio, la mantenibilidad del código disminuirá gradualmente hasta el final de su vida. El código es así y los comentarios del código correspondiente también son así.

Con respecto a los comentarios de código, no sé si ha experimentado contenido similar:

Puede que todos sean recuerdos dolorosos, pero esta es la degradación de los comentarios que acabo de describir.

Para el código, tenemos muchas metodologías y patrones de diseño para dividir las responsabilidades del código lo más claramente posible y ampliarlo. En cuanto a los comentarios, creo que la mejor manera es "no escribir comentarios" (esto se discutirá nuevamente en un capítulo posterior).

Mientras no escribas comentarios, no habrá ningún problema con los comentarios. La razón de este problema es que normalmente las personas no pueden mantener las anotaciones perfectamente después de ajustar la lógica empresarial. La mayoría de las veces, cuando la lógica del código cambia, los comentarios se convierten directamente en parte del rompecabezas empresarial. Los desarrolladores no solo tienen que resolver la lógica en el código deteriorado, sino también tener cuidado con la tentación de comentarios incorrectos.

Al mismo tiempo, cuando el código se degrada y gradualmente se vuelve incontrolable, parece más fácil describir la nueva lógica con un comentario que volver a abstraer los resultados del código. Pero el problema que trae es: "tratar de utilizar comentarios para compensar los problemas de lógica del código". Obviamente, los comentarios no pueden ayudarle a abstraer el código, simplemente parecen retrasar la aparición del problema (o incluso introducir problemas más graves).

Entonces la idea de "no escribir comentarios" se puede describir desde otra perspectiva: dejar que el código comente por sí mismo. Esto es un hábito. Tomemos el ejemplo más simple:

Se puede cambiar a:

Incluso si se ajusta a:

Se puede ver que. el segundo método se refiere al uso del método dentro del objeto. Si el orden es solo un objeto de entidad generado automáticamente o un objeto de valor, entonces también se puede usar el tercer método.

La ventaja de este ajuste es que el código en sí se utiliza para describir la lógica, de modo que se evite escribir comentarios tanto como sea posible.

En cuanto al argumento de no escribir comentarios, además de la interpretación automática del código, existen muchas situaciones en las que los comentarios no son apropiados.

Entonces mi definición de método simple es que si la lógica real del método (excluyendo los corchetes) es de 5 a 7 líneas (mis propios estándares), puede considerarse un método simple. Leer los comentarios de dicho método puede resultar más complicado que mirar el código directamente.

Para algunas lógicas que no se pueden describir directamente en el lenguaje, creo que es mejor no escribir comentarios y dejar que lean el código directamente. De lo contrario, los comentarios ambiguos inducirán a error a la gente a entender. Por supuesto, para mí, si es un inconveniente y la lógica es describir con precisión con palabras en proyectos internos, publicaré un enlace a la wiki para una descripción gráfica. De esta forma, no habrá interferencias para los desarrolladores que no quieran leer los comentarios y, al mismo tiempo, la combinación de imágenes y texto hará que sea más fácil de entender.

El estándar JavaDoc requiere que cada parámetro esté definido, pero el problema que esto trae es que los comentarios de algunos parámetros suficientemente concisos son en sí mismos redundantes, por ejemplo:

Aunque se ve muy perfecto , pero no significa nada por sí solo. Entonces, para los nombres de variables que se explican por sí solos en el código (deberían explicarse por sí mismos), los comentarios de JavaDoc en realidad son innecesarios.

Los comentarios de comportamiento en el IDE reducirán en gran medida la legibilidad del código. Algunos pueden aparecer después de un código largo y otros pueden aparecer después de un código corto. Su formato no es fácil de unificar, por lo que ahora. El manual de desarrollo de Alibaba de amplia circulación añade claramente un comentario en la línea anterior.

De hecho, sigo usando firmas de usuario porque las he usado desde que creé la plantilla del documento. Pero, en principio, el hábito de firmar archivos Java proviene de los primeros días, cuando el control de versiones del código no estaba muy desarrollado. En el control de versiones moderno, la próxima vida del archivo está controlada por el control de versiones, por lo que las firmas de los usuarios ahora no tienen sentido.

El código comentado debe eliminarse directamente; de ​​lo contrario, interferirá con el personal posterior. Las personas pueden interactuar inconscientemente de manera lógica con el código comentado y asumir que esta parte se deja sola para el resto del propósito. Al igual que el artículo anterior, en el control de versiones más desarrollado de hoy, si el código comentado tiene su función especial, debe estar protegido por una rama separada, en lugar de un fragmento de código comentado que interferirá con el desarrollo comercial normal.

Si la función expresada por la anotación no tiene nada que ver con el método actual, significa que esta parte de la anotación no sirve completamente al método actual. Entonces no debería aparecer aquí, tal vez sería mejor colocarlo en otro archivo Léame o documento wiki.

Si se agregan anotaciones de funciones no actuales al método, esto causará: Si desea comprender la anotación, necesita conocer el contexto de la anotación, por lo que esta parte de la anotación en sí requiere explicación adicional. , que va en contra de la función de la anotación en sí.

Aunque esperamos que el código pueda completar directamente la función de explicación lógica sin utilizar comentarios, a veces el código no está completamente calificado. En términos generales, las siguientes situaciones son adecuadas para complementar los comentarios.

En ocasiones, se puede añadir una descripción de fondo adicional fuera del programa. Esto puede agregar condiciones de juicio adicionales cuando comprende la lógica del código pero no sabe por qué se implementa de esta manera. También puede ayudarle a confirmar qué consideraciones llevaron a la lógica del código actual, como por ejemplo:

En este caso, aunque es posible que no esté de acuerdo con el método de implementación anterior, al menos puede conocer su propósito y juzgar si Se pueden realizar ajustes comerciales.

El código son notas temporales realizadas en el código. Aunque es un comentario, tiene un significado diferente al de un simple comentario de código y se puede marcar. Pero debe recordar lidiar con TODO con regularidad; de lo contrario, se reducirá la sensibilidad de todos.

Advertir si un método empresarial o funcional no debe ejecutarse en determinadas circunstancias. Estas situaciones suelen ser una combinación de información sobre algunas situaciones comerciales o registros de errores generados en situaciones de producción reales. Estos comentarios realmente mejorarán la eficiencia de la resolución de problemas. Pero tenga en cuenta que esta parte del contenido puede verse afectada por corrupción de código. Fuera de tema: puede configurar etiquetas "@xxx" de diferentes colores en la idea. Por ejemplo, creé una nueva "@ATTENTION" y ajusté el contenido posterior a violeta para proporcionar las advertencias correspondientes.

De hecho, hay muchas opiniones sobre los puntos anteriores, que también son las opiniones de la mayoría de los programadores de todo el mundo. Y China tiene su propia sensación de ser un gran país: es un problema de idioma. El requisito previo para la autoexplicación del código mencionado anteriormente es comprender con precisión el significado del código. Y piénselo cuando nombre algunos modelos de dominio, ¿cuántos de ellos se encuentran a través de los resultados de Google Translate o Baidu? Es difícil definir un nombre de variable que describa con precisión la intención del desarrollador para dicho sustantivo resultante. Entonces, si esta es la premisa, creo que para los campos en el objeto especificado, o los nombres de parámetros, variables locales, etc., podemos restringir los nombres especificados en los atributos y nombres de métodos según corresponda, de modo que debido a la El nombre del método y otros conceptos se confunden. En pocas palabras:

Para nombres que no se describen con seguridad en inglés, es mejor utilizar comentarios para restringirlos.

El contenido principal de este artículo proviene del capítulo comentado en "Código limpio". Mi experiencia de lectura es principalmente que parte del contenido del artículo está dirigido a veteranos con una larga experiencia laboral. Es posible que tengan problemas de anotación debido a hábitos pasados, pero este problema no es obvio en la Internet china. Las diferencias en la lengua materna conducen al código; La naturaleza autoexplicativa del inglés se reduce, pero sigue siendo muy importante aprender bien inglés.

上篇: ¿Pueden los perros y gatos tener hurones en casa? 下篇: Cómo abrir una buena cafetería
Artículos populares