Interesante, la legibilidad aplicada al lenguaje natural se mide por la velocidad de lectura y comprensión. Supongo que se puede adoptar una regla simple, si un comentario de código en particular no mejora esta propiedad, se puede evitar .
¿Por qué comentarios?
Si bien, el comentario de código es una forma de documentación incorporada, existen múltiples formas en los lenguajes de programación de alto nivel para evitar la programación superflua "sobre documentada" (de código significativo) utilizando elementos del propio lenguaje. También es una mala idea convertir el código en listados del libro de texto de programación, donde las declaraciones individuales se explican literalmente de forma casi tautológica (tenga en cuenta el ejemplo "/ * increment i by 1 * /" en las respuestas ya proporcionadas), por lo que dichos comentarios son relevantes. Solo para programadores inexpertos con el lenguaje.
No obstante, es la intención de tratar de comentar el código "no documentado" (pero sin sentido) que es verdaderamente "la fuente de todo mal". La existencia misma de un código "insuficientemente documentado" es una mala señal, ya sea un desorden no estructurado o un truco descabellado de propósitos místicos perdidos. Obviamente, el valor de dicho código es cuestionable al menos. Desafortunadamente, siempre hay ejemplos, cuando es mejor introducir un comentario en una sección de líneas de código (agrupadas visualmente) que envolverlo en una nueva subrutina (tenga en cuenta la "consistencia tonta" que "es el duende de las mentes pequeñas") .
Código legible = código comentarios
El código legible no requiere anotaciones de comentarios. En cada lugar particular del código, siempre hay un contexto de una tarea que se supone que este código particular debe lograr. Si falta el propósito y / o el código hace algo misterioso, evítelo a toda costa. No permita que trucos extraños llenen su código; es el resultado directo de la combinación de tecnologías de buggy con falta de tiempo / interés para comprender las bases. ¡Evita el código místico en tu proyecto!
Por otra parte, Programa legible = código + documentación puede contener varias secciones legítimas de comentarios, por ejemplo. para facilitar la generación de documentación "comentarios a API".
Siga los estándares de estilo de código
Lo suficientemente gracioso es que la pregunta no es sobre por qué comentar el código, se trata del trabajo en equipo: cómo producir código en estilo altamente sincronizado (que todos los demás pueden leer / entender). ¿Está siguiendo algún estándar de estilo de código en su empresa? Su propósito principal es evitar escribir código que requiera refactorización, es demasiado "personal" y "subjetivamente" ambiguo. Así que supongo que, si uno ve la necesidad de usar el estilo de código, hay una gran variedad de herramientas para implementarlo correctamente, comenzando por educar a las personas y terminando con la automatización para el control de calidad del código (numerosas ediciones, etc.) y (revisión). control integrado) sistemas de revisión de código.
Conviértete en un evangelista de lectura de códigos
Si acepta que el código se lee con más frecuencia de lo que está escrito. Si una expresión clara de ideas y pensamiento es importante para usted, no importa qué lenguaje se use para comunicarse (matemáticas, código de máquina o inglés antiguo). Si su misión es erradicar una forma aburrida y fea de pensamiento alternativo ... (lo siento , el último es de otro "manifiesto") .. haga preguntas, inicie discusiones, comience a difundir libros sobre la limpieza de códigos (probablemente no sea algo similar a los patrones de diseño de Beck, sino más bien a los ya mencionados by RC Martin ) que aborda la ambigüedad en la programación. Además, se incluye un pasaje de puntos clave de ideas clave (citado en el libro O'Reilly sobre legibilidad)
- Simplifique la asignación de nombres, los comentarios y el formato con sugerencias que se aplican a
cada línea de código
- Refine los bucles, la lógica y las variables de su programa para reducir la complejidad y la confusión
- Problemas de ataque en el nivel de la función, como reorganizar bloques de código para realizar una tarea a la vez
- Escriba un código de prueba efectivo que sea exhaustivo y conciso, además de legible
Cortar "comentar", a uno todavía le queda mucho (supongo que escribir código que no necesita comentarios es una pieza de gran ejercicio). Nombrar identificadores semánticamente significativos es un buen comienzo. Luego, estructurando su código agrupando operaciones conectadas lógicamente en funciones y clases. Y así. Un mejor programador es un mejor escritor (por supuesto, asumiendo otras habilidades técnicas).