Esta pregunta me ha estado obsesionando durante los últimos 2 meses.
Hace un tiempo, un amigo que es un gran programador me dio algunos códigos de ejemplo, y por primera vez noté un estilo único de organización de comentarios. Se esforzó por diseñar comentarios de una manera que me hiciera sentir más cómodo con el código en sí. Por ejemplo:
///////////////////////////////////////////// // //
// This code prints a basic "Hello world" //
// message to the console screen. You can //
// change the text in the brackets. //
// //
/////////////////////////////////////////////
#include <iostream>
int main() {
cout << "Hello world";
}
cuando podría simplemente haber escrito
/* This code prints a basic "Hello world" message to the console, change text in brackets */
#include <iostream>
int main() {
cout << "Hello world";
}
Este tipo de ejemplo solo a mayor escala. Esto me parece poco productivo en situaciones profesionales, pero en una situación de aprendizaje, parece ideal.
La pregunta aquí es si el estilo de comentario afecta cómo el lector entiende el código. En mi opinión personal, la opción n. ° 1 es más bonita a la vista y más fácil de seguir que la n. ° 2. ¿La forma en que comentas sobre el código afecta la capacidad de comprender tu código, o es solo una pérdida de tiempo y espacio?
Respuestas:
si
El diseño de un programa desde una perspectiva de espacios en blanco y comentarios tendrá un gran impacto en qué tan bien un desarrollador puede leer su código.
Prettier to the eye and more easy to followson subjetivos y no serán los mismos para todos los programadores.Dicho esto, algunos desarrolladores prefieren ver más código en la pantalla a la vez, mientras que otros prefieren tener más espacios en blanco / comentarios.
Al final del día, se sentirá más cómodo leyendo el código que está acostumbrado a leer.
El tío Bob Martin, autor de Clean Code, argumenta que los comentarios se usan con frecuencia para excusar el código incorrecto y deben evitarse siempre que sea posible. En cambio, su código en sí mismo debe ser legible y organizado lo suficientemente bien como para permitir que otro desarrollador lo recoja fácilmente y comience a trabajar.
fuente
Creo que el formato de código puede hacer una gran diferencia en la legibilidad, pero el código bien formateado (o incluso con sangría constante) me da una sensación cálida y confusa de que el escritor realmente se cuidó un poco, en lugar de simplemente cortar-n- pegando cualquier fragmento que tenga a mano.
No estoy tan seguro de los comentarios. Código que escribo, creo firmemente que el comentario ayuda. Por otro lado, si quiero comprender el código "empresarial" que encuentro en el trabajo, borro habitualmente todos los comentarios, reformateo el código para que tenga una sangría consistente, e imprimo en papel para leer en detalle, marcando bloques básicos con lapiz, etc.
Esta contradicción (yo: buenos comentarios; todos los demás: comentarios engañosos) me hace pensar que los comentarios están muy sobrevalorados. Incluso la mía.
fuente
Sí, comentar el estilo afecta la legibilidad (¿cómo puede no serlo?), Pero diría que el ejemplo que dio es un estilo muy pobre. El formateo excesivo es solo eso: excesivo.
Escribir buenos comentarios es una habilidad para practicar y refinar, al igual que escribir código.
fuente
En mi humilde opinión, el primero es adecuado para comentar sobre lo que hace una clase o al comienzo de un archivo fuente; el segundo es adecuado para describir lo que hace el siguiente bloque de código. para los métodos, usaría
Además de otras excelentes respuestas, creo que la coherencia en el estilo de los comentarios es otro punto. Si usa diferentes tipos de estilos de comentarios para el mismo tipo de tareas que perjudicaría bastante la legibilidad de su código.
fuente
El ejemplo que da es un poco extremo, pero sí, los comentarios tienen una función muy importante.
El escritor del código tiene un modelo mental de lo que necesita hacer. Los comentarios sirven para
De esa manera, si los requisitos cambian, es más probable que los cambios correspondientes en el código se puedan realizar correctamente, ya sea por el autor original o cualquier persona que venga más tarde.
También es bueno intentar escribir el código de tal manera que se explique por sí mismo, pero rara vez es 100% exitoso, por lo que los comentarios son necesarios.
fuente
Una respuesta rápida a la pregunta es "Sí". Los comentarios y el estilo de los comentarios afectan claramente la legibilidad y la comprensión del código. Esa es la idea general, pero la calidad de las descripciones de comentarios y su diseño es puramente subjetiva.
¿Alguna vez has intentado leer el código y los comentarios de otra persona? La mayoría de los programadores escriben código y comentarios basados en su propio estilo y nivel de conocimiento. Leer sus comentarios y códigos es como tratar de entrar en su mente y seguir sus prácticas.
Una forma de evitar este problema es utilizar una "guía de principios / estilo" básica que describa brevemente las pautas básicas para la estructura, el propósito y los comentarios del código. Esta guía debe ser seguida constantemente por las personas que escriben el código y todos los demás que podrían leer el código y posiblemente extenderlo.
fuente
Estilísticamente, iría con dos formas de comentario (para C ++ / Java)
o
un IDE con resaltado de sintaxis es suficiente para llamar su atención sobre el comentario, no necesita hacerse elegante con el formato.
fuente
Sí, el estilo de comentario ciertamente afecta la legibilidad. Cualquier estilo de comentario que me permita identificar los comentarios rápidamente para que pueda evitar leerlos ayuda enormemente cuando lo que realmente estoy tratando de hacer es leer el código .
Aún mejor es un estilo de comentario de código que me permite usar el IDE para minimizar los comentarios directamente fuera de la vista, por lo que no tengo que gastar la energía para leerlos.
fuente