4 - comentarios El comentario más valioso es aquel que no se tiene que escribir NO comentar código incorrecto, es mejor reescribirlo No hay nada más útil que un comentario en un lugar correcto, por otro lado, no hay nada peor que comentarios incorrecto No hay nada más dañino que un comentario viejo que mienta y desinforme Cuanto más viejo y alejado del código que describe, es mayor la probabilidad de que se equivoque Son un mal necesario Cuando escriba un comentario, piense si no existe otra forma de expresarlo a través del código Un comentario impreciso es peor que la ausencia de comentario Sólo el código dice la verdad respecto a lo que hace un comentario es útil cuando clarifica contenido que no podemos modificar para mejorar (como el uso de cosas de bibliotecas externas) Los comentarios TODO no son excusa para mantener código incorrecto No usar comentarios si se puede usar una función o una variable clara en su lugar Si se escribe un comentario, que describa el código que lo rodea, nunca información global fuera de contexto La conexión entre un comentario y el código que describe debe ser evidente, si se molestó en escribir un comentario, al menos asegúrese que el lector entenderá su significado Una función breve no requiere explicación y un buen nombre funciona mejor que un comentario en el encabezado No compensan código incorrecto El código incorrecto es la principal motivación para crear comentarios Un código claro y expresivo es mucho mejor a un código complejo con muchos comentarios, en lugar de invertir tiempo comentando código, resuélvalo Comentarios legales Aquellos por estándares corporativos, como los de derechos de autor (no son contratos legales.

Capítulo 3 (Funciones) El hacer software es como cualquier otro proceso creativo, primero se estructuran las ideas y después el mensaje, hasta que se lea bien. El primer borrador puede estar desorganizado, pero se retoca y se mejora hasta tener la forma adecuada. Deben ser de tamaño reducido (máximo de 20 lineas) Sangrado (o anidado) de máximo 2 niveles, de lo contrario dificulta la lectura Hacen algo o responden algo, no ambas cosas (cambia el estado de una estructura/objeto o devuelve información del mismo, hacer ambas causa confusión) Hacer una sola cosa Solo DEBEN hacer una cosa, hacerlo bien y debe ser lo único que hagan Las funciones que hacen una sola cosa no se pueden dividir en secciones Las funciones hacen una cosa si sus instrucciones están en el mismo nivel de abstracción El código se debería poder leer como un texto (de arriba a abajo); El primer párrafo P0 describe en un nivel de abstracción, el segundo párrafo P1 detalla la abstracción de la primera instrucción del párrafo anterior (P0) y así sucesivamente, de manera que cada uno describe el nivel de abstracción, mientras hace referencia a los párrafos posteriores del siguiente nivel Usar nombres descriptivos Cuanto más reducida y concreta sea una función, más sencillo será elegir un nombre descriptivo Un nombre descriptivo extenso es mejor que uno breve pero enigmático No tema dedicar tiempo a elegir un buen nombre; pruebe con varios nombres y lea el código con todos ellos hasta encontrar uno lo bastante descriptivo No es extraño que la búsqueda de nombres descriptivos genere una reestructuración favorable Use las mismas frases, sustantivos y verbos para los módulos Argumentos de funciones El número ideal de argumentos para una función es 0, después 1 y 2 Siempre que sea posible evite 3 argumentos Más de 3 argumentos requiere una justificación especial y NO es muy habitual Son más complicados desde el punto de vista de pruebas; tener que probar todas las permutaciones de valores en los argumentos es titánico en comparación con una función sin argumentos o con 1 argumento Los argumentos de salida son mucho más difíciles de entender que los de entrada; antes de la programación orientada a objetos, los argumentos de salida eran necesarios.

Capítulo 2 (Nombres con sentido) Crear nombres correctos La longitud de un nombre DEBE corresponder al tamaño de su ámbito El nombre de una clase NO debe ser un verbo Métodos DEBE tener nombres de verbo No tener miedo a molestias por cambio de nombre de variables (siempre que sea para mejor) Revelan intenciones ¿Por qué existe? ¿Qué hace? ¿Cómo se usa? Si un nombre requiere un comentario, entonces no revela su cometido Evitar desinformación No usar palabras lejanas al significado que se pretende Evitar nombres con variaciones mínimas: MethodUsedForHandlingOfStrings MethodUsedForEfficientStorageOfStrings Distinciones con sentido NO crear código solo para compilador/intérprete Nombres con series numéricas (a1, a2) no son intencionados, desinforman Palabras adicionales son redundantes (a, an, the, variable, info, data, table, NameString son ejemplos) // Son nombres distintos pero con el mismo significado class Product class ProductInfo class ProductData Pronunciables Usar nombres pronunciables (a los humanos se nos dan las palabras, si no lo puede pronunciar no lo puede explicar) Buscables Nombres de una letra y constantes numéricas NO son fáciles de localizar Evitar codificaciones Al codificar tipos o ámbitos en un nombre se dificulta la decodificación NO es razonable que nuevos empleados tengan que aprender otro lenguaje de codificación además del código a trabajar.

Capítulo 1 El código representa los detalles de las especificaciones (requisitos) El código incorrecto supone obstáculos: Se busca sortear marañas de código, buscando un camino o pistas de lo que sucede, encontrándose confusión y código sin sentido. Si el código incorrecto es un obstáculo ¿por qué se escribe? Prisa; tiempos de entrega No hay tiempo para un buen trabajo (jefe recala tiempo de limpieza de código) Deseo de terminar con premura Malas decisiones: Un código incorrecto que funciona es mejor que nada Lo resolveremos después Después es igual a NUNCA Dedicar tiempo a código correcto no solo es rentable, es supervivencia profesional Es responsabilidad del jefe defender objetivos y requisitos, es responsabilidad nuestra defender el código con la misma intensidad.

(Un pequeño prefacio) Pues ya había iniciado este libro hace poco, pero como siempre retengo mejor la información luego de escribirla, lo volví a comenzar de nuevo so pretexto de tomar anotaciones mientras lo leo (con suerte se me pega algo). Cabe aclarar que estas anotaciones son de carácter personal, sin afán de reproducir contenido del libro, aunque claro que la prosa se podría parecer en momentos (estoy leyendo el contenido del mismo, a final de cuentas).