Escribiendo un documento de diseño de software eficiente – CodesCode

En este artículo, hablaré sobre un proceso típico que sigo para comprender a fondo un problema y entregar una solución exitosa.

El diseño de software juega un papel vital en la vida de un ingeniero de software. Comienza con una declaración del problema y establece el camino para implementar una solución. En este artículo, hablaré sobre un proceso típico que sigo para comprender a fondo un problema y entregar con éxito una solución.

Declaración del problema

Definir una declaración del problema es la primera y crucial fase del proceso de desarrollo. Estas declaraciones provienen del producto, el liderazgo o otros ingenieros. Un problema bien definido proporciona una imagen muy clara de cómo debería ser el sistema. Pero a menudo, por muy bien definida que esté la declaración del problema, hay muchas ambigüedades e incógnitas. Para superar esto, procedemos a recopilar requisitos.

Recopilación de requisitos

Una vez definida la declaración del problema, por ejemplo, desarrollar una aplicación de chat, desarrollar un sitio de microblogging, etc. El siguiente paso es descifrar el problema, enumerar los requisitos, señalar las incógnitas y las dependencias y explicar las suposiciones. Permíteme explicar cada sección:

1. Descifrar la declaración del problema: Una frase que describe el problema es una explicación muy general de lo que el objetivo final de los interesados. A menudo, esta es una declaración muy abstracta. Para diseñar un sistema eficiente, primero necesitamos comprender la declaración del problema haciendo varias preguntas aclaratorias como “¿quiénes son los usuarios”, “¿qué características se requieren”, “¿cuáles son las restricciones”, etc. Esto proporcionará una buena comprensión de lo que se pide.

2. Enumera los requisitos: Siempre es mejor documentar y obtener una aprobación antes de la implementación. Una vez que la declaración del problema está clara, los requisitos se pueden desglosar en funcionales y no funcionales, y se pueden priorizar como P0, P1, P2, etc., en función del tiempo, la complejidad, etc. Esto actuará como un plan de lo que se debe entregar y para cuándo.

3. Señalar incógnitas y dependencias: Una vez que los requisitos están finalizados, estamos en condiciones de señalar las dependencias e identificar las incógnitas. A menudo, para sistemas pequeños o grandes, hay dependencias en las aplicaciones existentes o en las nuevas aplicaciones. Estas dependencias son tanto internas al equipo como entre equipos/organizaciones, y podrían representar un riesgo si no se resuelven a tiempo. Deben ser señaladas en el documento de diseño para que los interesados conozcan los riesgos y se resuelvan de manera prioritaria.

4. Suposiciones: Ningún sistema es perfecto y siempre hay ciertas suposiciones que debemos hacer debido a limitaciones tecnológicas, limitaciones de dependencias, incógnitas o suponiendo que cierto servicio existente se comportará de cierta manera, etc. Documentar esto te ayudará durante la fase de desarrollo y también en la entrega.

Cálculos aproximados

Los cálculos aproximados son muy importantes para diseñar tu sistema. Te ayudan a entender a tus clientes y tomar decisiones sobre la elección de infraestructura, almacenamiento, escalabilidad, etc., para satisfacer las necesidades de los clientes. Esto incluirá comprender el patrón de tráfico, el volumen de datos, el tipo de datos, los requisitos de almacenamiento, etc., lo que a su vez te ayudará a decidir qué componentes utilizar en tu sistema.

Descomposición de tareas

Una vez que los requisitos son precisos, podemos dividir estos requisitos en varias tareas o hitos. Esto dará a los lectores/interesados una idea clara sobre los plazos de entrega de los componentes de la aplicación. Esto también nos ayudará a hacer un seguimiento del progreso y reorganizar las prioridades si es necesario. Una vez que se descomponen los entregables, será más fácil crear historias/tareas y asignarlas a varios desarrolladores en paralelo.

Diseño de alto nivel

El paso muy crucial y importante: el diseño del sistema. Un diseño de alto nivel es un plan de tu aplicación y una guía para los desarrolladores. Una vez que los requisitos están claros, nos da un entendimiento muy profundo del sistema. En función de los requisitos, identificamos los diversos componentes necesarios para diseñar el sistema. Un diseño de alto nivel está compuesto por estos componentes e interacciones entre ellos. También se enumeran los actores, la infraestructura y las interacciones entre ellos. Para proporcionar una mejor visibilidad, también puedes agregar leyendas, numeración y marcas a estas interacciones. A menudo, hay no uno, sino muchos componentes/servicios diferentes existentes y nuevos que interactúan juntos. Siempre es mejor utilizar códigos de color o separaciones para agrupar los componentes relacionados. Esto brinda a los lectores una comprensión clara de las interacciones entre los componentes y sus límites.

Diseño de bajo nivel

Un diseño de alto nivel debe seguir un Diseño de Bajo Nivel (opcional según la complejidad). Un diseño de alto nivel muestra los componentes e interacciones a un nivel muy alto, mientras que el diseño de bajo nivel explica cada componente en detalle. Esto proporciona una visibilidad clara sobre cada componente individual y servirá como una estrella polar para los desarrolladores que trabajan en esos componentes. Puedes incluir tantos detalles como diagramas de clases, interacciones, jerarquía, etc., en este segmento.

Diagrama de Flujo

Cada aplicación de software consiste en un conjunto de comandos y pasos de ejecución para lograr una tarea deseada. Cada ejecución produce un conjunto de flujo de datos entre varios componentes que dicta cómo se comportará la aplicación. Por ejemplo, llama a API ‘a’ y luego utiliza ese resultado para tomar decisiones y llamar a API ‘b’. Una vez que se invoca la API ‘a’, se debe validar la autenticación y autorización antes de tomar cualquier decisión comercial. Esto se puede visualizar mejor en un diagrama de flujo. Esto proporcionará una visualización del flujo de datos, control, acciones, etc.

Otras Consideraciones

Una vez que hayas completado los pasos anteriores, tendrás un documento de diseño en muy buena forma. Hasta ahora, el documento tendrá suficiente información para derivar la tarea, el resultado y un camino para realizarlos. Pero muchas veces una solución no se ajusta para todos y para llegar a una solución óptima, debes considerar diferentes enfoques. Es una buena práctica documentar todas esas consideraciones alternativas con los pros y los contras de cada una de ellas. Al final, puedes concluir tu enfoque con una explicación de alto nivel de por qué elegiste el diseño anterior. Esto brinda a los lectores una imagen clara de tu elección de diseño y su profundidad técnica.

Esquema de Datos

Una vez que se completen el HLD y LLD, tendrás una comprensión clara de los diferentes componentes. Estos componentes ya sea alojarán tus aplicaciones, almacenarán datos, llamarán a componentes inferiores o realizarán alguna lógica de negocio. En esta sección, puedes describir todos los esquemas de datos y relaciones utilizadas en el diseño. Esto ayudará a los desarrolladores a implementar estos esquemas de manera clara y también ayudará a los lectores a comprenderlo.

Estructura de la API

Si el sistema requiere una API, entonces este es el mejor lugar para describir cada una de las APIs. Puedes escribir los detalles del punto final, detalles de la ruta, tipo de método, autenticación, autorización, estructura de las solicitudes y respuestas para cada API.

Costo de Ejecución

Este es otro aspecto importante del diseño del sistema. En esta sección, puedes describir todas tus elecciones de diseño y los costos de ejecución para el tráfico proyectado. Esto dará a los lectores una mejor comprensión del costo de ejecución de tu sistema, así como cualquier optimización futura que se pueda realizar para reducir costos.

Seguridad

La seguridad no es necesaria a menos que ocurra algún incidente. Por lo tanto, siempre es mejor considerar el aspecto de seguridad en tu diseño, como autenticación, autorización, almacenamiento de datos, encriptación en el almacenamiento, encriptación en reposo, eliminación criptográfica, política de acceso, clasificación de datos, etc. ¿Qué sucederá si algo sale mal? ¿Qué sucederá si se comprometen las claves? ¿Cómo asegurar el almacenamiento seguro de los datos? etc.

UX

Si tu diseño requiere UX, puedes agregar una sección con bocetos, prototipos, etc.

Detalles de Prueba

Puedes escribir detalles de alto nivel sobre cómo se puede probar el flujo. Dependiendo del diseño, esto puede ser un nuevo documento separado para describir las pruebas de cada flujo.

Excelencia Operacional

La excelencia operativa juega un papel importante y vital en una aplicación saludable. Este es un pilar muy importante de una aplicación bien diseñada y desarrollada. Puedes utilizar esta sección para describir la implementación, el mantenimiento, las alarmas, el panel de control, etc., para garantizar la salud de la aplicación.

Condiciones de Falla

Por último, pero no menos importante, las condiciones de falla. Cada sistema tiene cierto umbral a menos que se alcance. Puede haber condiciones de carrera, casos límite, dependencias descendentes, capas de almacenamiento, etc., que podrían provocar fallas. Es bueno describir estas condiciones de falla y un mecanismo para recuperarse de ellas.

Además de lo anterior, también puedes mencionar el Apéndice, Modelado de Datos, Discusiones, etc., en tu documento de diseño. El diseño del sistema es subjetivo y esta redacción es exclusivamente mi idea de un buen documento. ¡No dudes en proporcionar tus opiniones!