design - tag - Mejorando la legibilidad del código

name tags free (10)

Cuando se trata de documentación de código, generalmente se acepta que el código debe explicarse , y la documentación del código en línea (excluyendo la documentación API pública) solo debe explicar los problemas del metacódigo, como soluciones temporales, explicaciones sobre por qué se eligieron implementaciones específicas, etc.

¿Cómo logras que tu código sea más legible y se explique más?

Editar: además de los comentarios generales, también estoy buscando consejos específicos. Entonces, si dices "nombres de variables cortas pero significativas", sería bueno que también recibas una sugerencia útil (por ejemplo, "usa el principio de las tres palabras").

Echa un vistazo a la publicación del blog Smells de Jeff Atwood. Lo resume bastante bien. Agregaré mi ethos personal cuando se trata de un buen código legible:

Consistencia: esto se aplica al formateo, utilizando llaves, nombrando (variables, clases, métodos) y el diseño del directorio (si entierras un directorio fuente en algún lugar en / css voy detrás de ti con un machete);
Tamaño: si una función no cabe en su totalidad en la pantalla en un IDE normal con un tamaño de letra normal, entonces necesitas una muy buena razón por la que no. Por supuesto, hay algunos casos válidos para funciones mucho más largas, pero son ampliamente superados por los ejemplos atroces. Descompóngase según sea necesario para mantener sus funciones simples;
Comenta juiciosamente: hay una tendencia de algunos programadores a usar comentarios como sustituto de un código legible o simplemente comentar por el simple hecho de comentar (como /* finished */ comments justo antes de return true; .En serio, ¿cuál es el punto? Most ( bueno) el código se explica a sí mismo;
Nunca corte y pegue dentro de un proyecto: es perfectamente aceptable tomar un fragmento de código de un proyecto a otro (cada proyecto es una isla) pero nunca debe tomar un segmento de código no trivial desde un proyecto a otro punto dentro del proyecto . Inevitablemente uno cambia y deja a un desarrollador deficiente la tarea de mirar estos dos o más segmentos de código tratando de descubrir cómo (y posiblemente lo más importante, por qué) son diferentes; y
Evite el código repetitivo: si se encuentra escribiendo la misma secuencia de enunciados (o muy similar) una y otra vez, resuma o parametrítelo. Si ve declaraciones muy similares, la tendencia es descuidarlas suponiendo que son todas iguales (cuando normalmente no serán de una manera que sea importante).

El código de auto-documentación es:

Buenas convenciones de nombres
Diseño claro y separación de responsabilidades entre componentes (clase, función, etc.)

Recuerde, sin embargo, que incluso el código que más autosuporte solo puede documentar lo que hay allí; nunca lo que se omitió intencionalmente, se optimizó, se intentó y se descartó, etc. Siempre tendrá cierta necesidad de inglés, básicamente, en sus archivos de origen, o dejará fuera importantes advertencias y decisiones de diseño.

El código de limpieza del libro de "tío bob" le da una visión bastante buena de cómo deberían ser las funciones, con ejemplos prácticos.

Algunos puntos importantes:

pequeñas funciones, clases
buenos, significativos, nombres, el tamaño no importa, pero debe ser exactamente el tiempo que sea necesario
El espacio vertical entre las funciones / variables debe ser bajo (declarar cosas lo más cerca posible de donde se usa por primera vez)
las funciones y las clases deberían hacer una cosa y una sola cosa

El libro tiene muchas más reglas pequeñas, realmente lo recomiendo. También obtenga Code Complete 2.

Evita codejunk.

Edward Tufte tiene este hermoso y poderoso concepto de chartjunk , elementos visuales en una tabla que contribuyen al ruido en lugar de a la información. Al pensar en los cuadros de esta manera, hacemos gráficos mucho más claros.

Creo que el mismo tipo de pensamiento, aplicado al código, nos aporta un código mucho más limpio. Los ejemplos incluyen /* getFoo() gets the foo */ comentarios de estilo /* getFoo() gets the foo */ , paréntesis y llaves innecesarias, nombres de variables excesivamente específicos y verrugas húngaras.

Lo que constituye chartjunk depende del equipo, el entorno y el proyecto, algunas personas les gustan las verrugas; algunos entornos procesan el código de maneras que hacen que ciertos elementos no deseados sean útiles (por ejemplo, piense en corchetes y // end for comentarios); algunos proyectos requieren comentarios más extensos para cumplir con los estándares o documentar exhaustivamente una API. Pero cuando un equipo tiene estándares establecidos de lo que significa Chartjunk para sus proyectos, muchas decisiones se vuelven más fáciles, y su código se vuelve más consistente y más legible.

Generalmente no hago comentarios dentro del código, sin embargo, estoy totalmente en desacuerdo con la opinión frecuente de que uno debe simplemente escribir un código legible y luego no necesita documentación.

Lo que sí creo que debe documentarse es tu interfaz . Con eso quiero decir que debe haber comentarios por encima de las clases y los métodos. No son métodos simples como configurar y obtener, por supuesto.

Las personas que usan clases y métodos escritos por usted no deberían tener que leer su código para comprender cómo usarlos. Por lo tanto, creo que uno debe documentar qué entradas legales y rangos de salida son importantes, así como importantes invariantes. Por ejemplo, una función toma un puntero como argumento. No importa qué tan bien nombre su función, nunca puede ser obvio si el suministro de NULL es válido o si NULL es un resultado devuelto válido. A menudo, -1 y 0 se utilizan para señalar algo parecido al objeto buscado no encontrado o similar. Eso debe ser documentado.

Aparte de eso, creo que la clave para documentar el código no es documentar qué es o qué es una clase o método, sino cuál es la intención detrás de él.

Quédese con el paradigma utilizado en el entorno que está codificando.

Un ejemplo obvio es usar el caso de Pascal para los métodos en .NET, camel case en Java.

Ejemplos menos obvios se relacionan con el uso de las mismas convenciones que las utilizadas en la biblioteca de clases estándar.

Hay mucho que decir sobre este objetivo. Las convenciones de nombres transmiten mucha información para humanos, y muy poca para el compilador. Cualquiera que haya consumido una API en un entorno que usa las convenciones de otro entorno ha notado cuánto se destaca el código alienígena.

La consistencia es una característica valiosa que reduce la carga cognitiva para un consumidor humano de código.

Tenga una Convención de Codificación entre usted y sus colegas. Comenzando con sangría, cubriendo los corchetes hasta "¿dónde viene el corchete: nueva línea, misma línea?"

En Visual Studio uno puede elegir y corregir este estilo. Ayuda a todos los demás en tu equipo a leer el mismo código. También hace que el seguimiento de historial en un sistema de control de versiones sea mucho más fácil cuando no tiene que distinguir entre ediciones ''vacías'' (cambio de estilo) y ediciones reales.

Todas las respuestas (y la pregunta) se basan en la suposición de que la legibilidad es responsabilidad exclusiva del escritor del código. Si realmente no quiere leer el código y tiene una lista de renunciar a la lectura ahora (el código huele) que coincide con el 99% del código disponible y realmente no quiere ni siquiera pensar mucho sobre lo que está haciendo el código, entonces no vas a encontrar ningún código legible.

Cualesquiera que sean las reglas que usemos hoy para hacer que nuestro código sea más legible, se verán anticuadas y estúpidas dentro de 10 años. Si realmente desea una mejor legibilidad del código, lea algún código antiguo (tenga en cuenta las modas del tiempo, que tuvo que ejecutarse en una máquina con la milésima parte de la velocidad y memoria que tiene), haga un esfuerzo para comprenderlo y alentar a otra persona hacer lo mismo.

Use buenos nombres de variables y métodos. Divida el código en piezas significativas que logren propósitos específicos. Mantenga sus clases cohesivas (todo funciona en conjunto) y desacopladas (hay pocas dependencias entre las clases). No te repitas (DRY). Siga los principios SÓLIDOS del Tío Bob (no las leyes, como él lo señala ) en la medida en que trabajan para mejorar el código.

Estilo de formateo coherente
Buen uso del espacio en blanco
Usando nombres cortos pero significativos
No demasiados comentarios (como usted menciona), pero cuando lo haga, comente los porqués del código y, si corresponde, los por qué no (¿por qué no se utilizó otra implementación, especialmente si parece que debería ser obvio hacerlo? asi que).
No optimice el código hasta que un generador de perfiles me diga que es lento o ineficiente