comments - texto - poner comentarios en php
¿Son suficientes más comentarios en código o simplemente un código simple, legible y fácil de mantener? (13)
A veces es realmente difícil decidir cuándo exactamente ha escrito suficientes comentarios para que alguien entienda sus intenciones.
Creo que uno necesita enfocarse más en escribir un código legible y fácil de entender que en incluir una gran cantidad de líneas de comentarios explicando cada detalle de lo que está sucediendo.
¿Cuáles son sus puntos de vista sobre esto?
Apunta al código que no necesita comentarios, pero no te culpes demasiado si fallas.
Básicamente, dejando de lado un comentario bueno pero posiblemente breve al comienzo de una declaración de clase / método / función y, si es necesario, un comentario introductorio al comienzo del archivo, un comentario sería útil cuando un comentario no tan común o una operación no tan claramente transparente está codificada.
Por lo tanto, por ejemplo, debe evitar comentar lo que es obvio (i ++; en un ejemplo anterior), pero lo que usted sabe es menos obvio y / o más complicado debe merecer una línea de comentario clara, inconfundible, brillante y completa, que naturalmente se presenta con un premio Nobel por el código más claro de la historia;).
Y no subestime el hecho de que un comentario también debería ser divertido; los programadores leen mucho más gustosamente si pueden burlarse intelectualmente de ellos.
Por lo tanto, como principio general, los comentarios no son abrumadores, pero cuando debe escribir uno, asegúrese de que sea el comentario más claro que pueda escribir.
Y personalmente no soy un gran admirador del código de auto-documentación (también conocido como código sin una sola maldita barra oblicua): después de meses que lo haya escrito (son solo días para mi escala personal) es muy probable que no pueda contarle al la verdadera razón para elegir ese diseño para representar esa parte de su inteligencia, entonces, ¿cómo podrían los demás?
Los comentarios no son solo esas cosas verdes entre las líneas de código; son la parte del código que tu cerebro está mejor dispuesto a compilar. Calificando como código PIN (risas) No puedo afirmar que los comentarios no sean parte del programa que estás escribiendo. Son solo la parte que no está dirigida a la CPU.
Creo que comentar lo suficiente para poder entenderlo si tuviera que revisar su código más adelante en la vida debería ser suficiente.
Creo que se desperdiciaría mucho tiempo si comentaras para todos; e ir por esta ruta podría hacer que tu código sea aún más difícil de entender.
Estoy de acuerdo en que escribir un código legible es probablemente la parte más importante, pero no dejes de lado los comentarios. Tómese el tiempo extra.
El argumento se basa en un falso dilema: o bien tu código es una horrible abominación y escribes toneladas de comentarios para explicar cada declaración y expresión, o tu código es una hermosa poesía que puede ser entendida por tu abuela sin documentación alguna.
En realidad, deberías esforzarte por lo último (bueno, tal vez no tu abuela sino otros desarrolladores), pero debes darte cuenta de que hay momentos en los que un par de comentarios aclararán una ambigüedad o harán que las siguientes diez líneas de código sean mucho más simples. Las personas que no abogan por ningún comentario son extremistas.
Por supuesto, se deben evitar los comentarios gratuitos. Ninguna cantidad de comentarios ayudará a que el código incorrecto sea más comprensible. Probablemente lo empeoren. Pero a menos que solo esté codificando sistemas triviales, habrá ocasiones en que los comentarios aclararán las decisiones de diseño que se están tomando.
Esto puede ser útil al atrapar errores. El código alfabético puede parecer perfectamente legítimo mientras está completamente equivocado. Sin los comentarios, otros (o usted seis meses después) tienen que adivinar su intención: ¿Quiso hacer eso o fue un accidente? ¿Es este el error, o es en otro lugar? Tal vez debería consultar la documentación de diseño ... Los comentarios son documentación en línea, visible justo donde lo necesita.
Decidir correctamente cuándo realmente existe la necesidad de comentarios es la clave.
El código legible debería ser la prioridad número 1. Los comentarios son, como ya escribió Paul Tomblin, para centrarse en la parte del por qué.
Intenta hacer que el código se explique a sí mismo. Una de las cosas más importantes es usar nombres significativos para clases, funciones, variables, etc.
Comenta las secciones que no se explican a sí mismas. Los comentarios triviales (p. Ej., I ++; // Añadir 1 a i) hacen que el código sea más difícil de leer.
Por cierto, cuanto más cerca esté el pseudocódigo que pueda trabajar, más autoexplicativo podrá ser su código. Este es un privilegio de los lenguajes de alto nivel; es difícil hacer un código ensamblador auto explicativo.
Intento evitar comentar lo más posible. El código debe ser auto explicativo. Nombre las variables y los métodos apropiadamente. Rompe los bloques de código grandes en métodos que tienen un buen nombre. Escriba métodos que hacen una cosa, la que usted les dio el nombre.
Si necesitas escribir un comentario. Hazlo corto. A menudo tengo la sensación de que si necesita explicar en detalle por qué este bloque de código hace esto y aquello ya tiene un problema con el diseño.
Los comentarios no están ahí para explicar lo que estás haciendo. Están ahí para explicar por qué lo haces.
Los estudios han indicado que la legibilidad óptima ocurre cuando tienes alrededor de 1 línea de comentarios para 10 líneas de código. Por supuesto, eso no quiere decir que deba mantener su ración en 1/10 y entrar en pánico si pasa de largo. Pero es una buena forma de darte una idea de cuánto deberías comentar.
También recuerde que los comentarios son un olor a código. Es decir que pueden ser indicativos de un código incorrecto, pero no son necesariamente así. La razón de esto es que el código que es más difícil de entender se comenta más.
Normalmente, soy un fan de los comentarios de la documentación que explican claramente la intención del código que estás escribiendo. Las herramientas de Spiffy como NDoc y Sandcastle proporcionan una forma agradable y consistente para escribir esa documentación.
Sin embargo, he notado algunas cosas a lo largo de los años.
La mayoría de los comentarios de la documentación realmente no me dicen nada que realmente no pueda deducir del código. Eso supone, por supuesto, que puedo hacer que las cabezas o las colas salgan del código fuente para empezar.
Se supone que los comentarios se deben usar para documentar la intención , no el comportamiento. Desafortunadamente, en la gran mayoría de los casos, esta no es la forma en que se usan. Las herramientas como NDoc y Sandcastle solo propagan el uso incorrecto de los comentarios al proporcionar una gran cantidad de etiquetas que lo alientan a proporcionar comentarios que le dicen al lector cosas que debería ser capaz de discernir del código mismo.
Con el tiempo, los comentarios tienden a no sincronizarse con el código. Esto tiende a ser cierto independientemente de si usamos o no el software de documentación, lo que pretende facilitar la documentación porque acerca la documentación al código que describe. A pesar de que la documentación está justo al lado del método, propiedad, evento, clase u otro tipo, los desarrolladores todavía tienen dificultades para recordar actualizarlo si cambia el comportamiento intrínseco. En consecuencia, la documentación pierde su valor.
Vale la pena señalar que estos problemas son, en general, debido al mal uso de los comentarios. Si los comentarios se utilizan únicamente como un medio para transmitir intenciones, estas cuestiones van por el camino del dodo, ya que es poco probable que la intención de cualquier tipo dado o sus miembros cambie con el tiempo. (Si lo hace, un mejor plan es escribir un nuevo miembro y desaprobar el anterior con una referencia al nuevo).
Los comentarios pueden tener un valor inmenso si se usan correctamente. Pero eso significa saber para qué se usan mejor y restringir su uso a ese alcance. Si no lo haces, lo que terminas teniendo es una plétora de comentarios que son incorrectos, engañosos y una fuente de trabajo pesado (a un costo mayor) ya que ahora tienes que eliminarlos o corregirlos de algún modo.
Vale la pena tener una estrategia para usar los comentarios de una manera significativa que les evite convertirse en un sumidero de tiempo, energía y dinero.
Por qué necesitas comentarios El nombre del método debe ser lo suficientemente claro como para que no necesite comentarios.
Ex:
// This method is used to retrieve information about contact
public getContact()
{
}
En este caso, getContact no necesita los comentarios
Solo comenten cuando agregue algo.
Algo como esto es inútil y definitivamente disminuye la legibilidad:
/// <summary>Handles the "event" event</summary>
/// <param name="sender">Event sender</param>
/// <param name="e">Event arguments</param>
protected void Event_Handler (object sender, EventArgs e)
{
}
No todo el código es autodocumentado.
Estoy en el proceso de solucionar un problema de rendimiento ahora. El desarrollador pensó que descubrió la fuente del cuello de botella; un bloque de código que iba a dormir por alguna razón. No hubo comentarios sobre este código, ni contexto de por qué estaba allí. Eliminamos el bloque y volvimos a probarlo. Ahora, la aplicación está fallando bajo carga donde no estaba antes.
Supongo que alguien se había topado previamente con un problema de rendimiento y puso este código para mitigar el problema. Si esa era o no la solución correcta es una cosa, pero algunos comentarios acerca de por qué este código está ahí ahora nos ahorrarían un mundo de dolor y mucho tiempo ...