¿Son más comentarios mejores en entornos de alta rotación?

Estaba hablando con un colega hoy. Trabajamos en código para dos proyectos diferentes. En mi caso, soy la única persona que trabaja en mi código; en su caso, varias personas trabajan en la misma base de código, incluidos los estudiantes cooperativos que van y vienen con bastante regularidad (entre cada 8-12 meses). Ella dijo que es liberal con sus comentarios y los puso por todas partes. Su razonamiento es que le ayuda a recordar dónde están las cosas y qué hacen, ya que gran parte del código no fue escrito por ella y podría ser cambiado por alguien que no sea ella. Mientras tanto, trato de minimizar los comentarios en mi código, colocándolos solo en lugares con una solución o error no obvio. Sin embargo, entiendo mejor mi código en general y tengo un control más directo sobre él.

Mi opinión en esos comentarios debería ser mínima y el código debería contar la mayor parte de la historia, pero su razonamiento también tiene sentido. ¿Hay alguna falla en su razonamiento? Puede desordenar el código, pero en última instancia podría ser bastante útil si hay muchas personas trabajando en él a corto y mediano plazo.

Los comentarios no abarrotan el código.

Y cuando lo hacen, bueno, cada IDE medio decente puede ocultar / doblar comentarios. Idealmente, la historia debe ser contada por su código, su documento de requisitos, su historial de confirmación y sus pruebas unitarias, y no por comentarios. Sin embargo, los comentarios excesivos solo pueden doler cuando los comentarios se concentran en el cómo y no el por qué, sin embargo, esa es una discusión diferente .

Creo que tanto usted como su colega están "en lo cierto", la diferencia es, por supuesto, que usted trabaja solo y ella en un equipo, que a menudo incluye desarrolladores sin experiencia. No tiene una filosofía muy diferente sobre los comentarios, sino requisitos muy diferentes para comunicar su código. El argumento "me ayuda a recordar" también podría provenir del hecho de que ella maneja mucho más código que usted, y lo más importante, el código producido por diferentes personas, cada una con sus propias preferencias y peculiaridades personales.

Al final del día, los comentarios de código, aunque sus defectos obvios, son la forma más simple y rápida de comunicar su código. Dependiendo de la composición y organización del equipo, incluso podría ser la única forma que se aplica al mínimo común denominador. Por lo general, me encuentro siguiendo tu filosofía de comentarios cuando trabajo solo y ajustándome a la de tu colega cuando trabajas en equipo, especialmente si se trata de una habilidad de equipo desequilibrada.

Los comentarios prolíficos en ese tipo de entorno están encubriendo un problema que debería resolverse de otra manera.

El código legible y de calidad nunca debería necesitar comentarios adicionales para explicar lo que hace. El único momento para comentar es cuando desea explicar por qué se hizo algo de una manera particular. E incluso entonces, esos comentarios podrían estar en los mensajes de confirmación de control de fuente.

Entonces, el problema que está resolviendo es que tiene que trabajar con estudiantes que no saben cómo escribir su código de manera legible. En mi opinión, saturar el código con comentarios es una solución débil para ese problema.

Las revisiones estrictas del código serían mucho más efectivas, tanto para mantener el código ordenado como para mejorar a esos estudiantes para el futuro, ya sea en la misma compañía o en otro lugar.

El problema con los comentarios es que tienden a no sincronizarse con el código realmente rápido. Esto significa que a menudo hay comentarios incorrectos engañosos o rotundos en el código, por lo que perjudican la legibilidad más de lo que ayudan.

El objetivo es hacer que una base de código sea fácil de entender y modificar. Puede hacerlo a través del uso liberal de los comentarios (aunque podría encontrarse con el problema de los comentarios de datos), o puede escribir código autodocumentado (tanto como sea posible), y solo usar comentarios para explicar el no trivial "por qué "preguntas. Cualquiera de los enfoques podría funcionar, pero tenga en cuenta que para modificar el código tendrá que comprender el código en sí, y no solo los comentarios. Entonces, si bien los comentarios pueden ayudarlo a comprender el código, al final del día probablemente todavía tendrá que entender el código en sí. Dicho esto, prefiero el enfoque de código autodocumentado. Parece ser una forma más directa de crear una base de código limpia.

"¿Son más comentarios mejores en entornos de alta rotación?"

Creo que bien pueden ser peores:

• Diferentes autores utilizarán diferentes estilos y niveles de detalles y no estarán interesados ​​en actualizar los comentarios de otras personas.

• La opinión de "Lo que hay que comentar" cambia de persona a persona.

• Continúan la práctica de escribir código que es difícil de leer con comentarios para explicarlo en lugar de código fácil de leer con nombres descriptivos.

• Mantener su formato y consistencia se convierte en un trabajo en sí mismo.

• Los nuevos usuarios tienen que aprender el estándar de 'formato' antes de poder hacer cambios rápidos.

Punto 1: la claridad es importante en entornos de alta rotación

Punto 2: la verbosidad no es claridad

Agregar comentarios a su código puede o no mejorar la claridad; depende de los comentarios que agregue. Y una vez que se alcanza una claridad óptima, los comentarios adicionales empeorarán la situación, no la mejorarán.

Si bien los comentarios son un componente de claridad, la calidad del código es un componente significativamente más importante. La inteligencia es lo opuesto a la claridad . Si la función del código no es evidente de inmediato a través de una lectura informal, entonces el código no es particularmente claro, y los comentarios (sin importar cuán alta calidad sean los comentarios) son un sustituto pobre e ineficaz del código claro.

Por ejemplo, rellenar una bandera en el campo alto de un campo no relacionado puede ser perfectamente permitido en ciertas circunstancias, y puede tener mucho sentido desde una perspectiva de rendimiento en ciertas circunstancias, pero casi siempre es una mala idea con respecto a la claridad , incluso si comentas mucho.

Si tiene que explicar en prosa qué hace su código, considere cualquiera de los siguientes: Tenga en cuenta que algunos de estos pueden afectar el rendimiento, pero el rendimiento puede no ser tan importante como la claridad en ciertos casos.

• Mejores nombres de variables y nombres de funciones
• Mejor diseño de código y espaciado
• Elimina cualquier "truco" que creías que era una buena idea
• Agrupe el código según la función conceptual (por ejemplo, extraiga el código para un propósito específico en una función con el nombre apropiado, incluso si solo lo llama una vez)
• Use un algoritmo más directo (si las condiciones lo permiten)
• Utilice bibliotecas conocidas para una funcionalidad común.

Una respuesta simplificada: "Cuanto más probable sea que se vuelva a leer su código, mayor será la carga de explicar lo que está haciendo". Esto podría ser al hacer que el código sea más fácil de leer, al comentarlo, al crear documentación formal, al seguir los estándares de estilo ... Tenga en cuenta que podría ser usted quien está releyendo más tarde, aunque ciertamente también es cierto para otros en un ambiente de alta rotación.

Hay otro gran hilo que cubre si los comentarios son documentación o no.

Los comentarios son más útiles en algunos escenarios que en otros. Esto es tan fundamental que me preocupa cómo explicarlo en medio de tantas respuestas que percibo como "anti-comentario".

Si su código puede no leerse durante años, los comentarios son más importantes que si tiene una refactorización de código frecuente, una propiedad de código sólida y revisiones de código copiosas. Si su aplicación es compleja y utiliza técnicas que no son inmediatamente obvias para un observador competente en ese idioma, los comentarios son más importantes que si el sistema es un glorioso "Hola Mundo". Si la base del código no es tan estricta con los estándares como podría ser, los comentarios son más importantes que si está trabajando con seis capas de control de calidad. Si está trabajando en un equipo con ocho personas que solo están aprendiendo el idioma, los comentarios son más importantes que si su equipo tiene ocho Pulitzers de programación. Si tienes una aplicación en expansión en tu regazo,los comentarios son más importantes que si pudieras construirlo desde cero.

¿Sería mejor en la mayoría de esos escenarios corregir la causa subyacente en lugar de aumentar el uso de comentarios? Absolutamente. Pero a veces estás atascado con una base de código que tiene más huellas digitales que el teléfono inteligente de la ciudad, y la mejor manera de mejorarlo es hacer que tus cambios sean lo más legibles posible y comentar al máximo.

Para su problema específico: los comentarios no deben esparcirse tanto como para saturar el código. Un párrafo bien escrito en la parte superior de una subrutina, que describe por qué existe una función y tal vez por qué utiliza ese enfoque, es a menudo la mejor opción para ayudar al próximo programador a orientarse.