La mejor documentación: un buen código

Un buen código es como un buen chiste no requiere explicación.

Si tu código es auto explicativo, entonces no necesita comentarios y documentaciones, la mayoría de veces.

Un código bien escrito es como un carro con un buen equipo de música y porta vasos, que alcanza el limite de velocidad sin problemas. Cuando se daña, cualquier mecánico lo mete en su garaje y lo repara en seguida, usando herramientas comunes.

Un código mal escrito es como un carro que promete ser capaz de alcanzar 322 km/h, pero tiene un equipo de música que solo acepta casetes y los porta vasos no funcionan. Cada vez que intentas ajustar los retrovisores, el carro estalla en llamas y tiene que ser reparado exactamente por la persona que lo armó en la línea de producción, usando herramientas que parecen alienígenas.

Un buen código es como un libro bien escrito.

  • Fácil de entender
  • Bien dividido en capítulos que hace cada punto distinto

Un mal código es como un libro mal escrito.

  • Todos los capítulos hacen referencia a los otros, pero no esta claro de que trata cada capítulo
  • La misma cosa es descrita una y otra vez, sin razón aparente
  • El autor menciona varias excepciones a las reglas, y frecuentemente las contradice

Cosas que debes tener en mente si quieres escribir buen código:

  • Legibilidad — para ti y cualquiera que tenga que buscar en tu código
  • Mantenibilidad — mantén tu código fácil de modificar
  • Simplicidad no introducir sobre-compilaciones innecesarias
  • Eficiencia tu código debería correr tan rápido como pueda hacerlo
  • Claridad si tu código es auto explicativo, entonces no necesita comentarios y documentaciones, la mayoría de veces. Nombra tus métodos y propiedades de manera sensata. Rompe el código largo en pedazos más pequeños. Y nunca copies y pegues un bloque de código. Los comentarios y documentaciones son muy necesarias cuando se requiere. Un comentario es una pieza de texto legible para los humanos en el código fuente para explicar por qué existe algún pedazo de código.
  • Una baja cantidad de “WTF?!s” por minuto minimiza la frecuencia con la que otro desarrollador podría leer tu código y diga “WTF?!”

Prueba la calidad del código

Ten otro programador que nunca haya visto tu código, que lo lea mientras te lo explica mientras tu miras por encima de sus hombros.

Cuanto más fuerte es tu necesidad de detenerlo y explicar algo, más probabilidad de que tu código sea malo.

Si puedes sentarte calmadamente y con la boca cerrada, y no necesitan hacerte un montón de preguntas, tu código es probablemente bueno.

Sabes que estas escribiendo buen código cuando:

  • Las cosas son inteligentes, pero no demasiado inteligentes
  • Los algoritmos están optimizados, tanto en lectura como en velocidad
  • Las clases, variables, y funciones están bien nombradas y hacen sentido sin tener que pensarlo mucho
  • Cuando puedes volver al código después de un fin de semana, y puedes volver directamente a él sin perderte
  • Las cosas que van a ser reusadas son reusadas
  • Los métodos tienen a ser cortos y, preferiblemente realizan una sola tarea
  • Tiene suficiente información para llamar un método sin tener que buscar el código dentro de él
  • Cuando cada clase tienen un objetivo único, claramente definido, separada de otras clases con otros fines claramente definidos
  • Cuando tienes que volver atrás y agregar/modificar una característica, debería ser fácil
  • Cuando los bloques try/catch son tan pequeños como puedan

Gracias por leer, si te gusto no olvides compartir.

Fuente [ Free Code Camp ]

Anuncios

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión /  Cambiar )

Google photo

Estás comentando usando tu cuenta de Google. Cerrar sesión /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión /  Cambiar )

Conectando a %s