Código de Calidad RCO
Regla 1: sigue la guía de estilo
Cada lenguaje de programación tiene una guía de estilo que le explica con gran detalle cómo sangrar su código, dónde colocar espacios y llaves, cómo nombrar cosas, cómo comentar, todas las buenas y malas prácticas. Por ejemplo, la guía de estilo le dice los 12 errores que se esconden en este fragmento de código:
for(i=0 ;i<10 ;i++){
Lea la guía con cuidado, aprenda los conceptos básicos de memoria, busque casos en las esquinas, aplique las reglas religiosamente y sus programas serán mejores que los escritos por la mayoría de los graduados universitarios.
Muchas organizaciones personalizan las guías de estilo para reflejar las prácticas específicas de la organización. Por ejemplo, Google ha desarrollado y publicado guías de estilo para más de una docena de idiomas. Estas guías están bien pensadas., so check them out Si buscas ayuda para la programación de Google. Las guías incluso incluyen la configuración del editor para ayudarlo a aplicar un estilo de programación, y las herramientas personalizadas pueden verificar que su código se adhiere a ese estilo. Usa estas herramientas
Regla 2: Crear nombres descriptivos
Limitados por teletipos lentos y torpes, los programadores en el pasado solían contratar los nombres de sus variables y rutinas para ahorrar tiempo, pulsaciones de teclas, tinta y papel. Esta cultura persiste en algunas comunidades, en nombre de la compatibilidad con versiones anteriores; Considere la función de "torcer la lengua" de & C & nbsp; wcscspn & nbsp; Pero no hay excusa para esta práctica en el código moderno.
Use nombres largos y descriptivos, como & nbsp; complementSpanLength, para ayudarse a usted mismo, ahora y en el futuro, así como a sus colegas para comprender qué hace el código. La única excepción a esta regla se refiere a las pocas variables clave utilizadas dentro del cuerpo de un método, como un índice de bucle, un parámetro, un resultado intermedio o un valor de retorno.
Aún más importante, piensa mucho antes de nombrar algo. ¿Es el nombre exacto? ¿Quiso decir & nbsp; peakPrice, en lugar de & nbsp; bestPrice? ¿Es el nombre lo suficientemente específico para evitar tomar más de lo que es justo en el espacio semántico? ¿Debería nombrar su método & nbsp; getBestPrice, en lugar de & nbsp; getBest? ¿Su forma coincide con la de otros nombres similares?
Si tiene un método & nbsp; ReadEventLog, & nbsp; no debe nombrar a otro & nbsp; NetErrorLogRead. Si está nombrando una función, ¿el nombre describe lo que la función devuelve?
Por último, hay algunas reglas de nomenclatura fáciles. Los nombres de clase y tipo deben ser sustantivos. Los nombres de los métodos deben contener un verbo. En particular, si un método devuelve un valor que indica si algo es verdadero para un objeto, el nombre del método debe comenzar con & nbsp; es. Otros métodos que devuelven la propiedad de un objeto deben comenzar con & nbsp; obtener, y los que establecen una propiedad deben comenzar con & nbsp; establecido.
Regla 3: Comentario y Documento
Comience cada rutina que escriba (función o método) con un comentario que describa lo que hace la rutina, sus parámetros y lo que devuelve, así como los posibles errores y excepciones. Resuma en un comentario la función de cada archivo y clase, el contenido de cada campo de clase y los pasos principales del código complejo. Escribe los comentarios a medida que desarrollas el código; Si crees que los agregarás más tarde, te estás engañando a ti mismo.
Además, asegúrese de que su código en su totalidad (por ejemplo, una aplicación o biblioteca) incluya al menos una guía que explique lo que hace; indicando sus dependencias; y proporcionar instrucciones sobre la construcción, prueba, instalación y uso. Este documento debe ser corto y dulce; un solo archivo README es a menudo suficiente.
Regla 4: No te repitas
Nunca copie y pegue el código. En su lugar, abstraiga las partes comunes en una rutina o clase (o macro, si es necesario), y úselas con los parámetros apropiados. En términos más generales, evite las instancias duplicadas de datos o códigos similares. Mantenga una versión definitiva en un solo lugar y deje que esa versión conduzca a todos los demás usos. Los siguientes son algunos buenos ejemplos de esta práctica:
- Creación de guías de referencia de API a partir de comentarios, utilizando Javadoc o Doxygen.
- Detección automática de pruebas unitarias a través de una anotación o una convención de nomenclatura
- Generación de documentación en PDF y HTML a partir de una única fuente de marcado
- Derivación de clases de objetos de un esquema de base de datos (o lo contrario)
Regla 5: verifique errores y responda a ellos
Las rutinas pueden regresar con una indicación de error, o pueden generar una excepción. Tratar con él. No asuma que un disco nunca se llenará, su archivo de configuración siempre estará allí, su aplicación se ejecutará con los permisos necesarios, las solicitudes de asignación de memoria siempre tendrán éxito o que la conexión nunca se interrumpirá. Sí, un buen manejo de errores es difícil de escribir y hace que el código sea más largo y menos legible. Pero ignorar los errores y las excepciones simplemente barre el problema debajo de la alfombra, donde un confiado usuario final lo encontrará inevitablemente algún día.
Regla 6: Divide tu código en unidades cortas y enfocadas
Cada método, función o bloque de código lógico debe caber en una ventana de pantalla de tamaño razonable (25–50 líneas de largo). Si es más largo, divídalo en pedazos más cortos. Se puede hacer una excepción para secuencias de código repetitivas simples. Sin embargo, en tales casos, considere si podría conducir ese código a través de una tabla de datos. Incluso dentro de una rutina, divida las secuencias de código largas en bloques cuya función puede describir con un comentario al comienzo de cada bloque.
Además, cada clase, módulo, archivo o proceso debe referirse a una sola cosa. Si una unidad de código asume diversas responsabilidades, divídala en consecuencia.
Regla 7: usar las API de Framework y las bibliotecas de terceros
Conozca qué funcionalidad está disponible a través de una API en su marco de programación, y también lo que está comúnmente disponible a través de bibliotecas de terceros maduras y ampliamente adoptadas. Las bibliotecas soportadas por el administrador de paquetes de su sistema son a menudo una buena apuesta. Use ese código, resistiendo la tentación de reinventar la rueda (en una forma cuadrada disfuncional).
Regla 8: No diseñes demasiado
Mantenga su diseño centrado en las necesidades de hoy. Su código puede ser general para adaptarse a la evolución futura, pero solo si eso no lo hace más complejo. No cree clases parametrizadas, métodos de fábrica, jerarquías de herencia profundas e interfaces arcanas para resolver problemas que aún no existen, no puede adivinar lo que traerá el mañana. Por otro lado, cuando la estructura del código ya no se adapta a la tarea en cuestión, no se asuste de refactorizarlo a un diseño más apropiado.
Regla 9: ser consistente
Hacer cosas similares de manera similar. Si está desarrollando una rutina cuya funcionalidad se parece a la de una rutina existente, use un nombre similar, el mismo orden de parámetros y una estructura comparable para el cuerpo del código. La misma regla se aplica a las clases: asigne a la nueva clase campos y métodos similares, haga que se adhieran a la misma interfaz y haga coincidir los nombres nuevos con los que ya se utilizan en clases similares. Haga el pedido y el número de & nbsp; casos & nbsp; o & nbsp; si no, los & nbsp; bloques siguen la definición correspondiente en las especificaciones que está utilizando. Mantenga los elementos no relacionados en orden alfabético o numérico.
Su código debe adoptar las convenciones del marco en el que está programando. Por ejemplo, es una práctica común representar los rangos medio abiertos: cerrado (inclusivo) a la izquierda (comienzo del rango), pero abierto (exclusivo) a la derecha (el final). Si no hay una convención para una elección en particular, establezca una y sígala religiosamente.
Regla 10: Evitar las trampas de seguridad
El código moderno rara vez funciona de forma aislada. Por lo tanto, inevitablemente se arriesgará a convertirse en el objetivo de ataques maliciosos. No tienen que venir de internet; el vector de ataque podría ser datos ingresados en su aplicación. Según el lenguaje de programación y el dominio de la aplicación, es posible que deba preocuparse por los desbordamientos del búfer, los scripts entre sitios, la inyección de SQL y otros problemas similares. Conozca cuáles son estos problemas y evítelos en su código. No es dificil.
Regla 11: Utilizar estructuras de datos y algoritmos eficientes
El código simple a menudo es más fácil de mantener que el código equivalente ajustado a mano para mayor eficiencia. Afortunadamente, puede combinar la capacidad de mantenimiento con la eficiencia utilizando las estructuras de datos y los algoritmos proporcionados por su marco de programación. Use mapas, conjuntos, vectores y los algoritmos que funcionan en ellos, y su código será más claro, más escalable, más rápido y con menos memoria. Por ejemplo, si mantiene mil valores en un conjunto ordenado, una intersección de conjuntos encontrará los valores comunes con otro conjunto en un número similar de operaciones, en lugar de realizar un millón de comparaciones.
Regla 12: Incluir pruebas unitarias
La complejidad del software moderno hace que sea costoso implementar un sistema y difícil probarlo como una caja negra. Un enfoque más productivo es acompañar cada pequeña parte de su código con pruebas que verifiquen su correcto funcionamiento. Este enfoque simplifica la depuración al permitirle detectar errores antes, cerca de su origen. La prueba de unidad es indispensable cuando programa con lenguajes de tipo dinámico como Python y JavaScript, porque solo detectarán en tiempo de ejecución cualquier error que un lenguaje de tipo estático como Java, C # o C ++ detectaría en tiempo de compilación. Las pruebas unitarias también le permiten refactorizar el código con confianza. Puedes usar un xUnit framework para simplificar la escritura de estas pruebas y automatizar su ejecución.
Regla 13: Mantenga su código portátil
A menos que tenga alguna razón convincente, evite usar la funcionalidad que está disponible solo en una plataforma o marco específico. No asuma que los tipos de datos particulares (como los enteros, los punteros y el tiempo) tienen un ancho determinado (por ejemplo, 32 bits), porque esto difiere entre varias plataformas. Almacene los mensajes del programa por separado del código y no utilice convenciones culturales de código, como un separador decimal o un formato de fecha. Las convenciones deben cambiar cuando su código se ejecute en otros países del mundo, así que mantenga esta adaptación lo menos dolorosa posible.
Regla 14: Haz tu código edificable
Un solo comando debe construir su código en un formulario que esté listo para su distribución. El comando debe permitirle realizar construcciones incrementales rápidas y ejecutar las pruebas requeridas. Para lograr este objetivo, utilice una herramienta de automatización de compilación como Make, Apache maven, or Ant. Idealmente, debe configurar un sistema de integración continua que verificará, construirá y probará su código cada vez que realice un cambio.
Regla 15: Poner todo bajo control de versiones
Todos los elementos de su sistema (código, documentación, fuentes de herramientas, scripts de compilación, datos de prueba) deben estar bajo control de versión. Git and GitHub Haga esta tarea barata y sin complicaciones, pero hay muchas otras herramientas y servicios igualmente poderosos disponibles. Debería poder compilar y probar su programa en un sistema configurado correctamente, simplemente revisando el código del repositorio.