Memoria UD 04

Desarrollo de Aplicaciones Web – Entorno de desarrollo

Documentación y Refactorización

Clara Soriano Llorens

ÍNDICE

Introducción…...…….………………………………………………………………..pág. 3

¿Qué es la documentación?………….…...…….…………….…………………...pág. 4

¿Cuándo debemos hacer la documentación?………………...……………….. .pág. 5

Características de la documentación de software……………………………..…pág. 5

Tipos de documentación de software……………....……………………………. Pág. 6

Herramientas para realizar la documentación de software…….………………. Pág. 9

¿Qué es la refactorización?…………….…..…………...………………….……. .pág. 10

¿Cuándo debemos hacer refactorización?…..…..…………...………..….……. pág. 11

Code Smells…………………………………………………………..…...….……. pág. 11

Tipos de refactorización……………………………………………………………..pág. 13

Acoplamiento y cohesión……………………………………………………………pág. 14

Conclusiones…..……………………………………………………………………..pág. 16

Bibliografía web………………………………………………………………………pág. 17

UD04. Documentación y Refactorización Clara Soriano Llorens

2
INTRODUCCIÓN:

Recordemos que tenemos dos tipos de metodologías, la metodología ágil o de cascada

para la gestión de proyectos. Y es que esto depende de nuestro estilo de gestión y que
necesite el enfoque de la misma.

Una metodología de gestión de proyectos es un sistema de procesos que guían un

proyecto de principio a fin. Estas metodologías mantienen a los equipos en el camino y
establecen las reglas básicas para planificar, iniciar y trabajar en un proyecto. Disfrutando
de diferentes características, algunas detalladas y rígidas, y otras ligeras y flexibles.

La metodología ágil y la de cascada son dos metodologías populares que se

pueden utilizar mientras se trabaja con un sistema operativo de trabajo.

La metodología ágil es más adecuada para proyectos que no tienen un alcance definido
y en los que podrías enfrentar obstáculos que requieren cambios rápidos durante el
proceso. Esta metodología es iterativa, se adapta en función de los comentarios de los
clientes y las partes interesadas a lo largo del proyecto. Requiere un equipo de individuos
con iniciativa que colaboren y se adapten sin perder el ritmo.

La metodología de la cascada es más adecuada para los proyectos que tienen un

alcance claro y completo antes de que el proyecto comience. Si conoces todos los pasos
que un proyecto tendrá que atravesar para completarse y sabes que el riesgo de cambio
de alcance es bajo, el método de la cascada se convierte en una forma increíblemente
eficiente de completar un proyecto. Se requiere un equipo en el que cada miembro
entienda su rol y cumpla con todos los requisitos antes de pasar a la siguiente etapa de
desarrollo.

En ambos casos encontramos los dos conceptos que vamos a trabajar en esta memoria
que son la documentación y la refactorización y como esta ayuda a tus proyectos de
software a crecer y expandirse entre los usuarios más allá de los desarrolladores que lo
han generado.

UD04. Documentación y Refactorización Clara Soriano Llorens

3
 DOCUMENTACIÓN

¿QUÉ ES LA DOCUMENTACIÓN?

La documentación de los programas es un aspecto destacable, tanto en el desarrollo de la

aplicación como en el mantenimiento de la misma. Esta parte del desarrollo suele
menospreciarse sin valorar su potencial de organización del código, haciéndolo más
flexible y escalable. Ayudándonos incluso con la reutilización de partes de la aplicación y
sobre todo de los esquemas de diseño.

Evidentemente analizando el código podemos llegar a entenderlo, pero nos llevará un

tiempo extra que con la documentación no nos hará falta aplicar. Incluso si tú eres el que
más adelante tienes que dar soporte a la aplicación, aunque hoy conozcas el código a la
perfección, probablemente no será así en los próximos meses.

Si observamos con perspectiva el antiguo proceso de cascada vemos que incluía un

proceso donde se realizaba toda la documentación de la aplicación a realizar y esta etapa
era requisito fundamental, ya que, a partir de ahí se definía todo lo que se iba a
desarrollar. Creándose las denominadas “biblias” de documentación que, al final, nadie
leía por completo, donde también era habitual que la documentación tampoco reflejase
fielmente el desarrollo del programa.

Entendemos por documentación el informe que guía a los desarrolladores, usuarios y

otros interesados a través del uso de una aplicación. Este recursos proporciona
información sobre como instalar, utilizar o mantener un software, y como referencia para
quienes necesitan aprender su código y arquitectura. Entendemos como documentación
el procedimiento por el cual se deja registro y almacenado la información clave para un
entorno informático. Este procedimiento se entiende como: usar, mantener, y desarrollar
la aplicación, incluyendo guías, tutoriales y referencias técnicas. Los detalles incluidos en
la documentación TI pueden abarcar desde contraseñas y credenciales hasta
configuraciones, procedimientos operativos normalizados, etc.

La documentación del programa es la información, disponible por escrito, sobre un

programa; el texto del programa en sí es parte de la documentación. La documentación
acompaña las diferentes fases de la creación de un programa. Existen diferentes
documentaciones que describen el estado del programa en diferentes etapas de
desarrollo. La documentación ayuda a prevenir errores y garantiza que el código cumpla
con los requisitos y expectativas del proyecto.

UD04. Documentación y Refactorización Clara Soriano Llorens

4
¿CUÁNDO SE HACE LA DOCUMENTACIÓN?

La documentación acompaña las distintas etapas del proyecto, que son iterativas y de
mejora constante. Hay algunas partes de la documentación que sí se realizan al principio,
como el modelo de dominio,nos ayuda a aclarar cuál es el vocabulario del cliente y fija el
conjunto de palabras que todos tendremos que usar al crear las piezas de software.
Algunos de los diagramas que pueden ayudar mucho a entender el problema y el flujo de
acciones de la aplicación son los de casos de uso y los diagramas de estado.

Sobre todo al principio del desarrollo de una aplicación, donde lo recomendable es

dedicar los esfuerzos a las partes más complejas o que representen los mayores retos
para el equipo, es importante realizar diagramas de clases de aquello que vamos a
desarrollar. De hecho, al realizar estos diagramas, en parte, ya estamos programando,
aunque no con código. Luego, lo largo de las distintas fases del desarrollo, se irán
creando nuevos módulos que pueden requerir nuevos diagramas. A medida que el
proyecto avanza, no será siempre necesario realizar documentación, pues seguramente
estaremos trabajando en módulos más sencillos o los módulos responden a una
arquitectura similar a la de otros ya existentes en la aplicación.

CARACTERÍSTICAS DE LA DOCUMENTACIÓN DE SOFTWARE:

Documentar es un proceso muy importante y esta documentación debe ser clara y

completa para reducir la curva del aprendizaje, facilitar la colaboración y minimizar los
problemas de mantenimiento a largo plazo, por lo que, sin una buena documentación,
cualquiera software puede volverse inaccesible e ineficaz.

La documentación es parte del software, lo que lo hace necesaria para su correcto uso y
mantenimiento, pese a que realizarla nunca es fácil, ya que hay que saber qué
documentar y como hacerlo, por ello son importantes los siguientes puntos:

- Documentación debe evolucionar con el software: es lógico que el software cambien

con el tiempo y su documentación también debe hacerlo para ser un reflejo de la
aplicación desarrollada, ya que una documentación obsoleta puede ser contraproducente.

- Documentación bien organizada y fácil de entender: sobre todo porque requiere ser
consultada rápidamente, y es preferible la creación de diagramas en lugar de textos.

- Los diagramas tienen que ser entendidos de manera idéntica por todas las
personas: es por ello importante el uso de un lenguaje como UML, el cual indica el
significado de cada uno de los elementos que forman parte de los diagramas.

- El lenguaje escritor debe ser claro, conciso y sencillo de entender: incluso por una
persona con menos conocimientos técnicos.

- Ofrecer menú de navegación dentro de la navegación: siendo conscientes de a quien

va dirigida.

Mantener una documentación correcta y actualizada es una tarea que lleva tiempo y al

UD04. Documentación y Refactorización Clara Soriano Llorens

5
desarrollar un proyecto es importante que se destinen suficientes recursos para su
realización.

TIPOS DE DOCUMENTACIÓN DE SOFTWARE:

En el desarrollo de software existen dos tipos de documentación: la documentación

referida al proceso de desarrollo y la documentación que aborda el producto. Cada
uno con sus correspondientes pautas, que veremos a continuación.

Documentación en el proceso de desarrollo:

Es importante realizar una documentación adecuada para entender bien qué se debe
programar y cómo se debe programar, más aún cuando el proyecto conlleva cierta
dificultad de desarrollo. La documentación se divide en dos categorías:

Interna: Es aquella que se crea en el mismo código, ya sea en forma de comentarios o de

archivos de información dentro de la aplicación.

Externa: Es aquella que se escribe en cuadernos o libros, totalmente ajena a la aplicación

en sí.

La guía técnica o manual técnico:

Es donde se reflejan el diseño del proyecto, la codificación de la aplicación y las pruebas

realizadas para su correcto funcionamiento. Generalmente este documento esta diseñado
para personas con conocimientos de informática, como programadores. El principal
objetivo es el de facilitar el desarrollo, corrección y futuro mantenimiento de la aplicación
de una forma rápida y fácil.

Esta guía está compuesta por tres apartados diferenciados:

Cuaderno de carga: Es donde queda reflejada la solución o diseño de la aplicación. Esta

parte de la guía es únicamente destinada a los programadores. Debe estar realizado de
tal forma que permita la división del trabajo

Programa fuente: Es donde se incluye la codificación realizada por los programadores.

Este documento puede tener, a su vez, otra documentación para su mejor comprensión y
puede ser de gran ayuda para el mantenimiento o desarrollo mejorado de la aplicación.

Pruebas: Es el documento donde se especifican el tipo de pruebas realizadas a lo largo

de todo el proyecto y los resultados obtenidos.

Pero en todo caso, la documentación que se entrega al cliente tendrá que coincidir con la
versión final de los programas que componen la aplicación. Una vez concluido el
programa, los documentos que se deben entregar son una guía técnica, una guía de
uso y de instalación.

UD04. Documentación y Refactorización Clara Soriano Llorens

6
La guía de uso o manual del usuario:

Contiene la información necesaria para que los usuarios utilicen correctamente la

aplicación. Este documento se hace desde la guía técnica pero se suprimen los
tecnicismos y se presenta de forma que sea entendible para el usuario que no sea
experto en informática. Un punto a tener en cuenta en su creación es que no debe hacer
referencia a ningún apartado de la guía técnica y en el caso de que se haga uso de algún
tecnicismo debe ir acompañado de un glosario al final de la misma para su fácil
comprensión.

La guía de instalación:

Es la guía que contiene la información necesaria para implementar dicha aplicación.

Dentro de este documento se encuentran las instrucciones para la puesta en marcha del
sistema y las normas de utilización del mismo. Además, de las normas de utilización se
incluyen también las normas de seguridad, tanto las físicas como las referentes al acceso
a la información. Algunos documentos que se realizan en esta etapa son:

• Requisitorio: En este caso se realizan documentos para saber qué se va a

desarrollar, indicando las funcionalidades de cada actor que interactúa con el
sistema. La fase de requisitorio puede incluir diagramas como los casos de uso,
diagramas de los procesos de negocio, mockups de las interfaces.

• Planificación: Durante el proyecto es importante saber qué recursos vamos a

destinar a cada tarea y cómo se van a organizar, los tiempos que se estima que
cada etapa ocupará. Para ello son útiles los diagramas de Gantt, que generalmente
se generan con el uso de alguna herramienta.

• Reportes del proceso de desarrollo: A medida que el desarrollo del proyecto se

va realizando es esencial reflejar en un documento el rendimiento de nuestro
equipo de desarrollo y el tiempo invertido en cada una de las disciplinas (gestión,
análisis y diseño, programación, pruebas, despliegue). Llevar unas métricas de
todo el proceso nos ayudará a ser conscientes de la inversión realizada, estimar de
manera más exacta las necesidades y previsiones en adelante, de modo que cada
vez sea más fiel el tiempo y dinero que un proyecto va a costar.

• Backlog de tareas: Es muy habitual que los equipos de desarrollo lleven

herramientas que permitan saber qué tareas se deben realizar en cada proyecto y
su urgencia, con un sistema ágil que ayude a decidir qué partes del proyecto se
van a acometer en cada iteración.

• Documentación del código: El código también se puede documentar con

bibliotecas que permiten convertir los comentarios en documentos que pueden
consultar los desarrolladores con facilidad. Cada lenguaje de programación tiene
sus propias herramientas para generar la documentación del código a partir de los
comentarios, como Javadoc o PhpDocumentor (PHP).

UD04. Documentación y Refactorización Clara Soriano Llorens

7
Documentación del producto:

La documentación del producto está especialmente dirigida a los usuarios finales de este
producto y el personal que se dedicará a darle mantenimiento o prestar soporte. Ya que
les permite entender mejor las características del mismo y tener una idea concreta de las
tareas que deben desempeñar. Podemos encontrar los siguientes documentos:

• Descripción del sistema: Guía a las personas que van a gestionar una
aplicación, indicando cuál es el objetivo de ésta, cuáles son sus requisitos
funcionales, los requisitos no funcionales y las restricciones o necesidades
especiales de las soluciones que se deben implementar.

• Guías de uso: Para los usuarios de la aplicación, donde especifique qué procesos
se encuentran disponibles y cómo se deben usar las aplicaciones.

• Descripción del sistema: Para las personas más técnicas, que les ayude a
entender la arquitectura de la solución, los sistemas que involucra y sus
interacciones. Qué requisitos deben tener las máquinas de despliegue, en aspectos
relacionados con la escalabilidad, seguridad y otros factores importantes que
ayuden al correcto mantenimiento de los sistemas.

• Arquitectura del software: Si nuevos desarrolladores se incorporan al trabajo es

importante tener una documentación sobre cómo está desarrollado el software y
sus principales líneas de diseño y arquitectura. Generalmente con diagramas UML
que permitan entender de una manera visual las diferentes piezas.

• Documentación del API: Además, si los clientes del software son otras piezas de
software, como ocurre en el caso de las API o servicios web, es importante
disponer de una completa documentación que especifique claramente la entrada y
salida de cada proceso. En este caso herramientas como OpenAPI o Swagger ya
que nos permiten generar toda la documentación mediante anotaciones en el
propio código.

UD04. Documentación y Refactorización Clara Soriano Llorens

8
HERRAMIENTAS PARA REALIZAR LA DOCUMENTACIÓN DE
SOFTWARE:

La elección de las herramientas adecuadas para la documentación de software es crucial

para simplificar el proceso y garantizar la calidad del material.

Confluence: es una plataforma de colaboración que incluye funciones avanzadas para la

creación y gestión de documentación. Su interfaz facilita la colaboración entre equipos y
simplifica la creación de documentación técnica. Esta herramienta utiliza una estructura
de espacios y páginas para organizar la información. Puedes crear páginas dedicadas a
diferentes aspectos de tu software, agregar imágenes, tablas y enlaces, y colaborar en
tiempo real con otros miembros del equipo.

Document360: es una plataforma de documentación técnica diseñada específicamente

para facilitar la creación y gestión de documentación de software. Esta herramienta
proporciona un editor intuitivo y sencillo para la creación de contenido. Permite la creación
de versiones, la personalización del diseño y la incorporación de elementos interactivos.
La plataforma también ofrece análisis para comprender cómo los usuarios interactúan con
la documentación.

Doxygen: es una herramienta de generación de documentación para código fuente. Está

diseñada para analizar el código y generar documentación automáticamente, reduciendo
la carga manual. Esta herramienta trabaja analizando comentarios específicos en el
código fuente, como los comentarios estilo JavaDoc o de C++. A partir de estos
comentarios, crea documentación en varios formatos, como HTML, LaTeX y RTF. Puede
generar diagramas de clase y colabora bien con proyectos grandes.

UD04. Documentación y Refactorización Clara Soriano Llorens

9
 REFACTORIZACIÓN

¿QUÉ ES LA REFACTORIZACIÓN?

Con la refactorización buscamos ser limpios y elegantes con el código, pero es posible
que en los inicios de la carrera de cualquier programador inexperto esto se convierta en
un problema, y es aquí, donde se hace necesaria la fase de refactorización.

Mediante la fase de refactorización cambiamos la estructura interna del software para

hacer más sencilla su comprensión y modificarlo haciéndolo más limpio, pero sin cambiar
su comportamiento.

UD04. Documentación y Refactorización Clara Soriano Llorens

10
¿CUÁNDO SE DEBE HACER REFACTORIZACIÓN?

Debemos refactorizar en dos ocasiones:

• Para mejorar la eficiencia y crear un algoritmo más rápido.

• Para reestructurar un código de planificación en la nueva estructura y mantener el

código o añadir características de forma más sencilla.

Al refactorizar podemos añadir nuevos errores, este es un punto a tener en cuenta, ya que
nos tenemos que concienciar para repasar el código y evitar errores, para ello es
necesario que pase un Test Driven Development.

Code Smells: Son señales e indicios de que es posible que haya un problema en el
diseño o estructura del código fuente del programa. No tienen porque ser errores por si
mismos, pero pueden indicar áreas problemáticas que podrían conducir a problemas más
graves en el futuro si no se abordan.

Algunos ejemplos de esto puede ser la duplicación de código, métodos

o funciones largos y complejos, nombres de variables poco descriptivos,
cases con demasiadas responsabilidades, dependencias excesivas
entre clases, etc.

Identificar y corregir los code smells es importante para mantener un

código limpio y fácil de entender. Esto ayuda a mejorar la calidad del
software y facilita su mantenimiento. Herramientas de análisis
estático de código y técnicas de revisión de código son comúnmente
utilizadas para detectar y abordar los codesmells en un proyecto de
desarrollo de software.

UD04. Documentación y Refactorización Clara Soriano Llorens

11
Patrones más habituales de Code Smells:

• Duplicated code: mismo código en muchas partes.

• Long method: Crear submétodos (en líneas de código de método).
• Large classes (en líneas de código de clase). Dividir la clase en subclases y/o
redistribuir sus funcionalidades.
• Long parameter list (parámetros de un método). Estudiar si el método está
cohesionado (realiza una única función)
• Divergent change (cambio divergente). Cuando una clase es frecuentemente
modificada por diversos motivos.
• Shotgun surgery (cirugía de escopeta). Si tras un cambio en determinado lugar, se
deben realizar modificaciones adicionales en diversos lugares para compatibilizar dicho
cambio. Reducir el acoplamiento (interdependencia entre módulos)
• Feature envy (Envidia de funcionalidad). Método que utiliza más cantidad de elementos
de otra clase que de la propia. Pasar el método a la clase cuyos componentes son más
requeridos para usar.

UD04. Documentación y Refactorización Clara Soriano Llorens

12
TIPOS DE REFACTORIZACIÓN DE SOFTWARE:

Tipos de mantenimiento para la codificación:

Evolutivo: Añadimos mejoras

Adaptativo: Cambios legales/coyunturales
Correctivo: Solución de errores
Perceptivo: Refactorización a posteriori.

El mantenimiento perceptivo es el único que suele realizar el autor de la fase de

codificación. El resto de mantenimientos suele realizarlo personas que no estuvieron
en la fase de codificación.

Refactorización continua: Si es antes de la fase de mantenimiento.

Refactorización a posteriori: Si es después de la fase de mantenimiento.

Cuando refactorizamos mejoramos la calidad y reducimos los tiempos, por el contrario,

refactorizar no está considerado como avance del proyecto para los clientes y no suele
haber tiempo para ello, justo lo que ocurre con la fase de documentación, pero que
peligros tiene la refactorización para que no se le preste tanta atención como se merece.

Peligros de refactorizar:

• Arma de doble filo. Siempre hay un código mejor. Cuidado con entrar en una espiral de
refactorización.
•Mantener la refactorización bajo control
• Debemos estimar tiempo máximo antes de comenzar a refactorizar.
• Refactorizar demasiado implica:
• Pérdida de tiempo (y dinero)
• Incremento de complejidad de diseño de tanto refactorizar
• Sensación de no estar avanzando
• Sensaciones anímicas negativas

UD04. Documentación y Refactorización Clara Soriano Llorens

13
Acoplamientos y cohesión:

Hay que reducir el acoplamiento entre módulos/métodos/clases. Esto se refiere al

grado de interdependencia entre los módulos o componentes de un sistema. Un
acoplamiento bajo implica que los módulos están débilmente interconectados, es decir,
que tienen poca
dependencia entre sí. Por otro lado, un acoplamiento alto indica una fuerte
interdependencia, lo que significa que los cambios en un módulo pueden tener un impacto
significativo en otros módulos.

Por el contrario, hay que aumentar la Cohesión de un módulo/método/clase hay que.

Esto refiere al grado en que las partes de un módulo están relacionadas entre sí y
trabajan juntas para cumplir un propósito común. Una alta cohesión implica que las partes
del módulo están estrechamente relacionadas y contribuyen de manera significativa al
mismo objetivo. Por el contrario, una baja cohesión indica que las partes del módulo
pueden
estar relacionadas de manera débil o que realizan múltiples tareas no relacionadas entre
sí. Por tanto, mientras que el acoplamiento se refiere a la relación entre distintos módulos,
la cohesión se refiere a la relación entre las partes internas de un módulo. Un buen diseño
de software busca minimizar el acoplamiento y maximizar la cohesión
para mejorar el mantenimiento,la flexibilidad y la reutilización del código.

Teniendo en cuenta todo lo expuesto, hay que buscar las ventajas de cada uno y
encontrar el balance que garantiza mayor simplicidad y coherencia. A modo gráfico, la
tendencia que deberíamos buscar sería movernos siempre hacia el cuadrante inferior de
la derecha, buscando bajo acoplamiento y alta cohesión.

UD04. Documentación y Refactorización Clara Soriano Llorens

14
Un bajo acoplamiento nos garantiza:

• Mejorar el mantenimiento de los módulos del software, facilitar los cambios en el

software sin tener que revisar todos los módulos dependientes.
• Mejorar la reutilización de las unidades del software.
• Facilitar las pruebas unitarias de cada módulo, al ser más independientes.

Por otro lado, una alta cohesión nos permite:

• Tener un código mas entendebile, legible y coherente.

• Mejorar la reutilización, al tener todo lo relacionado con una cosa, en esa cosa, y
no disperso entre módulos.
• Mejorar el mantenimiento del software, ya que todo está perfectamente localizado y
los cambios en un módulo no afectarán a módulos externos.
• Facilita las pruebas de caja negra, ya que toda la funcionalidad relacionada con
una cosa, está encerrada en esa cosa.

Existen técnicas y buenas prácticas para limitar el acoplamiento entre componentes,

como la Ley de Demeter o el principio «Tell, Don’t Ask«. Es difícil aplicarlo en el día a día
del desarrollo, aunque es bueno tenerlo en consideración.

UD04. Documentación y Refactorización Clara Soriano Llorens

15
CONCLUSIONES SOBRE DOCUMENTACIÓN DE SOFTWARE:

Esperamos que esta descripción de las necesidades y tipos de documentación te haya

resultado de utilidad. Para finalizar, queremos señalar de nuevo la importancia de realizar
una correcta documentación del producto, que ayude durante el proceso de desarrollo del
software y su mantenimiento a lo largo del tiempo. Esta documentación debe atender las
necesidades de gestores, programadores y de los clientes finales del producto.

Además, tan importante como realizar la documentación es mantenerla actualizada, lo

que lleva un tiempo considerable a lo largo de la vida útil de las aplicaciones. Este trabajo
no debe olvidarse a la hora gestionar el proyecto, asignando los recursos suficientes para
su realización.

CONCLUSIONES SOBRE REFACTORIZACIÓN DE SOFTWARE:

La refactorización ayuda a comprender el código y anima a cada desarrollador a pensar y

comprender las decisiones de diseño, en particular en el contexto de propiedad
colectiva/propiedad colectiva del código. La refactorización favorece la aparición de
elementos de diseño reutilizables (como patrones de diseño) y módulos de código.

La refactorización es el proceso de cambiar un sistema de software de tal manera que no

altere el comportamiento externo del código pero mejore la estructura interna. Es una
forma disciplinada de limpiar el código que minimiza las posibilidades de introducir
errores. Mejora el diseño del código.

UD04. Documentación y Refactorización Clara Soriano Llorens

16
BIBLIOGRAFÍA WEB

https://monday.com/blog/es/gestion-de-proyectos/metodologia-agil-o-de-cascada-que-tipo-
de-gestor-eres/
https://www.arsys.es/blog/hacer-documentacion-tecnica-software
https://desarrolloweb.com/articulos/importancia-documentacion.html
https://www.disrupciontecnologica.com/acoplamiento-y-cohesion/

UD04. Documentación y Refactorización Clara Soriano Llorens

17