¿Qué aprenderá?

¿Qué hará?

¿Cuáles son los prerrequisitos?

Inicio 1

Contexto 2

Open CMS 2

Codescene 3

Hotspots 5

Salud del código (Code health) 5

Distribución del conocimiento(Knowledge distribution) 6

Estadísticas de actividad 7

Mapas de flujo(Flow maps) 8

Visualizaciones de riesgo(Risk visualizations) 9

Estrategia del tutorial 11

Configuración del ambiente Codescene 11

Hacer fork del proyecto Open CMS 12

Crear cuenta en Codescene 12

Lanzar un análisis de código fuente en CodeScene 14

Navegar visualizaciones Hotspots y Code health 17

Navegar Hotspots 17

Navegar Code health 20

Navegar visualizaciones de arquitectura 21

Definir componentes de arquitectura en CodeScene 22

Créditos 23

Versión 1.0 23

Material de consulta complementario 23

Open CMS

En este tutorial analizaremos el código fuente del proyecto OpenCMS. OpenCMS es un Sistema de Gestión de Contenidos (CMS por sus siglas en inglés) de código abierto hecho en Java. El sistema permite la creación, gestión y publicación de contenido en sitios web de manera eficiente y sencilla. Entre sus características principales se encuentran: la capacidad de trabajar con múltiples sitios web, la gestión de permisos y roles de usuarios, la integración con sistemas de comercio electrónico, la personalización del contenido según el perfil del usuario y la integración con sistemas de búsqueda y estadísticas. OpenCMS cuenta con una comunidad activa de desarrolladores y usuarios que ofrecen soporte y recursos para su uso y mejora continua. Además, es compatible con estándares como JSP, XML y XHTML, lo que permite una fácil integración con otros sistemas y aplicaciones. Para más información sobre el sistema usted puede ir a https://demo.opencms.org/livedemo/overview/.

OpenCMS sigue una arquitectura basada en capas, compuesta por:

  1. Capa de presentación: Es la capa que se encarga de mostrar el contenido al usuario final. Utiliza plantillas y temas para dar formato al contenido y presentarlo de manera atractiva.
  2. Capa de aplicación: Esta capa gestiona la lógica de la aplicación, como la gestión de usuarios, la gestión de contenidos, la gestión de permisos y roles, etc. Está construida con tecnologías Java, como Servlets y JSP.
  3. Capa de datos: Esta capa se encarga de acceder y gestionar los datos que se almacenan en la base de datos. OpenCMS utiliza una base de datos relacional para almacenar la información de los sitios web.
  4. Capa de servicios: Esta capa se encarga de proveer servicios y funcionalidades adicionales, como la integración con sistemas externos, la gestión de sesiones de usuario, etc.

Codescene

CodeScene es una plataforma de análisis de software que ayuda a los desarrolladores y equipos de desarrollo a mejorar la calidad de su código y optimizar su proceso de desarrollo. La herramienta utiliza algoritmos avanzados de aprendizaje automático y herramientas de visualización de datos para proporcionar información sobre cambios en el código, deuda técnica y rendimiento del equipo. CodeScene es capaz de identificar patrones y tendencias que indican posibles problemas, como áreas de alta complejidad, "bad smells" en el código o silos de conocimiento. Esta información es muy valiosa para ayudar a los desarrolladores a tomar decisiones sobre cómo mejorar el código fuente y cómo trabajar de manera más eficiente dentro del equipo. En general, CodeScene tiene como objetivo ayudar a los equipos de desarrollo a crear mejores productos de software con menos esfuerzo y menos errores.

Existen otras herramientas con funcionalidades similares a Codescene, una de las más usadas es por ejemplo SonarQube. Ambas herramientas analizan código fuente estático ayudando a los desarrolladores a mejorar la calidad del software y a detectar problemas potenciales, pero existen algunas diferencias significativas entre Codescene y SonarQube. Por un lado, SonarQube es una herramienta open-source de análisis de código fuente que evalúa la calidad del código, la seguridad y el rendimiento. Ofrece un conjunto de reglas predefinidas y personalizables que permiten a los desarrolladores identificar problemas comunes en el código, como vulnerabilidades de seguridad, errores de codificación, duplicación de código y violaciones de buenas prácticas de programación. Además, SonarQube proporciona una interfaz de usuario web fácil de usar que muestra los resultados de las pruebas y el progreso en la solución de los problemas. Por otro lado, CodeScene es una herramienta de análisis de código que se enfoca en la gestión del conocimiento del software. Utiliza IA para analizar el código fuente y ayudar a los desarrolladores a identificar áreas problemáticas y a entender cómo se relacionan los diferentes componentes del sistema (es decir, la arquitectura). CodeScene también proporciona una perspectiva histórica del código, lo que permite a los desarrolladores ver cómo ha evolucionado el software con el tiempo. En general, si comparamos ambas herramientas, mientras que SonarQube se enfoca en la calidad y seguridad del código, CodeScene se enfoca en la comprensión y gestión del conocimiento del software.

Codescene usa un modelo de 4 factores (4 Factor Model) para evaluar la mantenibilidad del código fuente, este modelo está basado en los principios del Twelve-Factor App, una metodología para construir aplicaciones de Software como Servicio (SaaS). El modelo de los 4 factores está compuesto por:

  1. Salud del código (Code health): Este factor se centra en la estructura y organización de código fuente. Un código bien organizado es más fácil de entender, modificar y mantener con el tiempo.
  2. Distribución del conocimiento (Knowledge distribution): Codescene analiza el historial de commits de Git para identificar patrones de propiedad de código y distribución de conocimiento. Con la información del historial de commits, Codescene puede identificar qué partes del código fuente son modificadas con más frecuencia y por cuáles desarrolladores, generando visualizaciones que muestran la distribución del conocimiento en el equipo.
  3. Alineamiento del equipo y el código (Team-code alignment): En esté punto Codescene ayuda a identificar áreas del código fuente donde los miembros del equipo pueden tener diferentes opiniones o enfoques de codificación. Al analizar el historial de commits de Git, se puede identificar áreas del código donde diferentes miembros del equipo han realizado cambios conflictivos o donde las revisiones de código han resultado en una gran cantidad de comentarios y sugerencias.
  4. Despliegue (Delivery): Este factor analiza cómo se despliega y se mantiene el código fuente en producción. Un código fuente que es difícil de desplegar o que requiere intervención manual frecuente es menos mantenible que una que se puede desplegar fácil y automáticamente.

Al evaluar el código en función de estos cuatro factores, Codescene proporciona información sobre mantenibilidad de código y ayuda a identificar áreas en las que el equipo de desarrollo debe prestar más atención o áreas en donde se debería trabajar para mejorar la salud del código. Para esto, CodeScene proporciona varias métricas y tipos de visualizaciones.

En cuanto a las métricas incluye clásicas (por ej., número de archivos, LOC, número de commits, etc. ) y otras más sofisticadas (por ej., esfuerzo Codescene y salud del código) que explicaremos más adelante. En cuanto a los tipos de visualizaciones, sigue una descripción general de la cartografía que CodeScene obtiene para el código de OpenCMS.

Hotspots

Es un mapa de calor que muestra las áreas del código fuente que son más propensas a defectos y deuda técnica. Esta gráfica incluye los filtros de "Code health filter" y "Commit frequency filter", al igual que una función llamada "Combine Aspects", que permite resaltar en la gráfica los "Hotspots", los puntos con baja salud "Low Code Health", puntos con "Defects" (issues reportados) y costos o "Costs" (habilitada si existe integración con otras herramientas que permiten saber costos aproximados de desarrollo).

Figura XX: Mapa de calor de Hotspots.

Salud del código (Code health)

Es un gráfico de radar que muestra la salud del código fuente, incluyendo unas estadísticas (por ej., frecuencia de cambio del código escrito, pérdida del conocimiento, etc.) y una representación del estado de salud de las clases usando los colores del semáforo, yendo del rojo al verde. Donde el rojo representa a una clase con muchos bad smells (por ej., complejidad ciclomática, duplicaciones) y verde con muy pocos. A continuación, se describen las componentes de interacción (acciones) que permite esta visualización:

Figura XX: Mapa de calor de salud del código

Distribución del conocimiento(Knowledge distribution)

Es una visualización que muestra cómo se distribuye el conocimiento entre los miembros del equipo y los riesgos potenciales asociados con los silos de conocimiento.

Figura XX: Dashboard de distribución de conocimiento

Estadísticas de actividad

Es una visualización que muestra cómo ha evolucionado el código fuente a través del tiempo en términos del número de commits y autores.

Figura XX: Ejemplos de gráficas de actividad, commits en el tiempo y contribuidores activos.

Mapas de flujo(Flow maps)

Son visualizaciones que muestran cómo fluyen los cambios de código a través del tiempo, destacando cuellos de botella y áreas de baja eficiencia. Estas vistas están incluidas en la versión enterprise. Por ejemplo, en la figura que sigue se muestra la gráfica "Lead time for changes" la cual tiene en el eje de las "x" las semanas y en el eje de las "y" el tiempo que se ha tomado el equipo para hacer algún tipo de cambio en el código. Por ejemplo, la gráfica obtenida para Open CMS muestra que, a la 2° semana de julio de cierto año, el tiempo para aplicar cambios en el código ha sido de 20 días. Adicionalmente, la gráfica muestra una tendencia creciente en ese número de días lo que pueden indicar problemas organizativos/de planificación/deuda técnica creciente.

Figura XX: Tiempos de espera para cambios

Visualizaciones de riesgo(Risk visualizations)

Codescene incluye diferentes visualizaciones que muestran riesgos a nivel de los individuos, por ejemplo, es posible ver si existe riesgo de pérdida de conocimiento si un desarrollador va a dejar de trabajar en el proyecto y reconocer si desarrolladores actuales son islas de conocimiento en algunas partes del código.

Figura XX: Mapa de calor de riesgos de conocimiento

En esta vista es posible filtrar por desarrollador o equipo, en el campo "Filter by authors and teams" y ver si existe algún tipo de riesgo en algunas partes del código debido a que un equipo o desarrollador es una isla de conocimiento en partes específicas del código o si existen múltiples desarrolladores activos y no hay riesgos de fuga de conocimiento. La figura anterior muestra los archivos en los que el/la desarrollador (a) gWestenberger es quién más ha hecho contribuciones, por tanto hay un riesgo de pérdida de conocimiento si él/ella deja el proyecto. Esto puede motivar decisiones, por ej., que otros desarrolladores se familiaricen con el código previamente desarrollado por gWestenberger.

En esté tutorial comenzaremos explicando cómo crear una cuenta en CodeScene y lanzar un primer análisis. Para lanzar un análisis, es necesario contar con un repositorio de código open source en nuestra cuenta de Github, nosotros usaremos el repositorio de OpenCMS, por lo cual, también explicaremos cómo hacer fork del proyecto en Github. En la segunda parte de este tutorial, usted navegará las principales visualizaciones proporcionadas por CodeScene y explicaremos cómo estás pueden ayudar a entender el estado del código fuente, por último, explicaremos la funcionalidad de componentes de arquitectura ofrecida por CodeScene, que permite definir grupos de archivos, ver cómo estos grupos evolucionan en el tiempo y el estado del código fuente en términos de la salud del código, puntos de atención o distribución del conocimiento. Cada uno de estos pasos se estructuran en secciones. Las secciones pueden tener asociadas vídeos que muestran el paso a paso. Al principio de cada sección hay una anotación que aclara lo que se espera que el/la estudiante haya logrado al terminar la sección.

The domain of the requested iframe () has not been whitelisted.

Hacer fork del proyecto Open CMS

Codescene, en su versión community, acepta el análisis de código fuente opensource conectándose directamente a GitHub, por lo cual, usted deberá realizar una copia del código de OpenCMS haciendo fork al siguiente repositorio en GitHub: https://github.com/alkacon/opencms-core

Este repositorio tiene actividad desde el 2001, por lo que Codescene podrá darnos diferentes vistas para entender la evolución del repositorio, esto gracias a que la herramienta analiza todos los commits de los diferentes contribuidores.

Crear cuenta en Codescene

Para abrir una cuenta en Codescene usted deberá ingresar a la página de la plataforma en https://codescene.com/community-edition. Enseguida, de clic en Start Community Edition

En el siguiente paso logueese en la cuenta de Github con la que hizo fork del repositorio de OpenCMS.

Lanzar un análisis de código fuente en CodeScene

Para realizar el análisis de un repositorio, usted deberá dar clic en el botón Add new project en la parte superior derecha de la página principal.

En seguida, Codescene mostrará una lista de los repositorios disponibles en la cuenta de Git asociada. Escoja en la lista el repositorio de OpenCMS al que le hizo fork y de clic en Continue.

En la siguiente pantalla coloque un nombre al proyecto y de clic en Save and run Analysis.

El análisis puede tardar algunos minutos, Codescene informará cuando el proceso haya culminado.

Una vez realizado el análisis, tendrá disponible una serie de visualizaciones dentro de la plataforma. Para ver el resultado del análisis diríjase al proyecto en la página principal de su cuenta de Codescene y dé clic en Dashboard. La página de entrada mostrará un resumen de algunas de las métricas y vistas relacionadas con el modelo de 4 factores.

Figura XX: Menu de CodeScene

Diríjase ahora en el menú a Scope, System trends. Aquí veremos una serie de gráficas con tendencias generales del sistema. Centraremos nuestra atención en una gráfica en especial, la gráfica de "Change frequency of files", para eso diríjase a la pestaña de Change Frequency Distribution.

Figura XX: Gráfica de frecuencia de cambio de archivos

La gráfica de "Change frequency of files" en CodeScene muestra la frecuencia con la que se han realizado cambios en los archivos de un repositorio de código durante un período de tiempo determinado. En la gráfica, el eje X representa el tiempo y el eje Y representa la frecuencia de cambio. Cada punto en la gráfica representa un archivo en el repositorio, y la altura de cada punto indica la frecuencia con la que se han realizado cambios en ese archivo.

Esta gráfica exponencial decreciente, es común en la mayoría de repositorios de código, describiendo dos comportamientos. Primero, al principio se agregan archivos de código que no son alterados en el futuro. Segundo, en la marcha y evolución del proyecto aparecen otros archivos que cambian constantemente, y por ende, son puntos de atención para análisis ya que los picos de actividad podrían estar relacionados con problemas de mantenibilidad del código, introducción de errores, etc. De esta gráfica, podemos extraer el número de cambios más alto que han sufrido los archivos del repositorio, para usarlo cómo filtro en otras vistas dentro de CodeScene. Esto nos permitirá ver cuáles son esos archivos que más cambios han sufrido y conocer con más detalle su salud.

The domain of the requested iframe () has not been whitelisted.

Navegar Hotspots

Diríjase en el menú de CodeScene a Code y luego al submenú Hotspot.

Se abrirá la gráfica de "Hotspots"

La gráfica de "Hotspots" en CodeScene muestra los archivos o secciones de código en un repositorio que tienen el mayor impacto en la calidad y mantenibilidad del sistema. En la gráfica, los archivos se representan como círculos, y el tamaño de cada círculo indica su tamaño en términos de líneas de código. El color de cada círculo indica el nivel de complejidad y riesgo del archivo, según la métrica de "hotspot" utilizada por CodeScene. La métrica de hotspot también se llama "CodeScene Effort". CodeScene Effort mide el esfuerzo necesario para mantener un archivo de código en el tiempo, teniendo en cuenta las siguientes propiedades:

  1. Complejidad: La complejidad es medida de varias maneras, como con el número de rutas de ejecución en el código de una función o clase, el número de atributos en una clase o el número de variables utilizadas en una función, etc.
  2. Cambio: Se utiliza la frecuencia de cambio para medir la cantidad de veces que se ha modificado el archivo. Los archivos que cambian con frecuencia pueden ser más difíciles de mantener, ya que los cambios pueden introducir errores y problemas en el código.
  3. Estabilidad: se utiliza la estabilidad del archivo para medir la cantidad de veces que el archivo ha sido modificado y cuánto tiempo ha pasado desde la última modificación. Los archivos que se modificaron al inicio del proyecto, pero que han permanecido estables durante un largo período de tiempo pueden ser más fáciles de mantener que los archivos que cambian con mucha frecuencia recientemente.

Al combinar estos factores, CodeScene Effort puede calcular el esfuerzo necesario para mantener un archivo de código en el tiempo. Los archivos con un alto valor de CodeScene Effort son los que tienen un mayor impacto en la calidad y mantenibilidad del sistema, y por lo tanto, pueden requerir más atención y esfuerzo por parte de los desarrolladores.

Además, en la vista, los círculos se agrupan en clusters, indicando que los archivos están relacionados entre sí porque se encuentran en una misma carpeta y por ende pueden requerir atención conjunta. La gráfica de Hotspots puede ayudar a los desarrolladores a priorizar su trabajo en las áreas más críticas del sistema, como los archivos con alta complejidad y riesgo, y también puede ayudar a identificar áreas de código que requieren una reestructuración para mejorar la calidad y mantenibilidad del sistema en general.

En la gráfica de "Hotspots" de CodeScene, se pueden aplicar diferentes filtros para enfocarse en áreas específicas del código. Algunos de los filtros más comunes son:

Estos filtros se pueden combinar para enfocarse en áreas específicas del código y obtener una comprensión más profunda de la calidad y mantenibilidad del sistema.

Navegar Code health

Diríjase ahora al tab "Code Health". Se abrirá la siguiente gráfica:

Al igual que en la gráfica de Hotspot, los archivos se representan como círculos, y el tamaño de cada círculo indica su tamaño en términos de líneas de código. En este caso, el color de cada círculo indica la salud del archivo en tres niveles de salud o sin nivel:

  1. Saludable (Healthy): Círculos de color verde que indican que el archivo no tiene problemas de salud de código.
  2. En peligro (Warning): Círculos de color amarillo indicando que la salud del código se encuentra en peligro por que ha estado decreciendo en los últimos cambios.
  3. Alerta (Alert): Circulos de color rojo en donde la salud del código es baja y requieren acciones rápidas para mejorar su salud.
  4. Sin puntuación (No score): Archivos en donde no es posible dar un nivel de salud del código fuente.

La salud del código (o code health) es una métrica cuyo valor va desde 10 (código saludable que es relativamente fácil de entender y evolucionar) hasta 1 (lo que indica código con graves problemas de calidad). CodeScene calcula el estado del código mediante una combinación de propiedades del código y factores organizativos (antipatrones, distribución del conocimiento, sobrecarga de los desarrolladores, clases Dios, etc.) . Los factores se correlacionan con mayores costos de mantenimiento y el riesgo de defectos. CodeScene pondera y califica los hallazgos de acuerdo con un amplio conjunto de datos de referencia de bases de código del mundo real para generar la métrica de salud de código normalizada. CodeScene utiliza las siguientes propiedades del código:

Todas estas métricas y análisis se combinan para calcular la salud general del código fuente en la gráfica de Codehealth de CodeScene. La gráfica proporciona una visión general de la calidad del código, lo que puede ayudar a los desarrolladores a identificar áreas que necesitan mejoras y a priorizar el trabajo en consecuencia.

The domain of the requested iframe () has not been whitelisted.

En CodeScene, la definición de componentes de arquitectura sirve para ayudar a los desarrolladores y arquitectos de software a comprender la estructura y complejidad del código fuente analizando conjuntos de componentes. Para CodeScene un componente de arquitectura es un bloque lógico dentro del sistema. Si lo que tenemos es una arquitectura de microservicios, podríamos definir cada microservicio como un bloque lógico. De manera similar, si nuestro código está compuesto por capas, por ejemplo, las capas de los patrones MVC, MVP, MVVM, etc., cada capa sería un bloque lógico dentro de CodeScene.

Un componente de arquitectura puede ser algo más general dependiendo de las necesidades de análisis de nuestro código. Por ejemplo, si tenemos un proyecto en donde estamos interesados en la coevolución del código de nuestra aplicación frente al código de pruebas, debido a que sospechamos que se dedica demasiado esfuerzo para mantener las pruebas actualizadas, podríamos definir solo dos componentes arquitectónicos: código de aplicación y pruebas automatizadas.

Definir componentes de arquitectura en CodeScene

En el menú izquierdo, diríjase a configuración y luego a Architectural components.

En esta ventana de clic en Architectural Component Editor. Se abrirá una gráfico de radar con los paquetes, subpaquetes y archivos del sistema. Aquí definiremos los componentes arquitecturales de nuestro sistema, creando paquetes para cada una de las capas de OpenCMS. Cada componente arquitectural se compone de una lista de archivos que se incluyen a traves de expresiones regulares simples a los archivos del proyecto. Para nuestro caso de estudio crearemos los siguientes componentes arquitecturales:

Presentation

opencms-core/test-gwt/**
opencms-core/webapp/**
opencms-core/src-gwt/**
opencms-core/src/jsp/**
opencms-core/src/ui/**

Business

opencms-core/src/**
opencms-core/test/**
opencms-core/src-modules/**

Data Layer

opencms-core/src/db/**

Utilities

opencms-core/src-setup/**
opencms-core/gradlew.bat

System

opencms-core/**

Para crear un componente architectural de click en select a component y luego de clic en "Create a new Component".

Luego en el modal, escriba el nombre del componente y en el campo "Pattern" escriba uno de los patterns que harán parte de este componente.

Es componente aparecera en la parte inferior de la página y desde allí podrá agregar otros Patterns dando clic en el botón Add pattern manually.

Realice esté proceso para todos los patterns descritos en esta sección.

Lanzar un análisis con los componentes definidos

Dirijase nuevamente a la ventada de configuración, pero esta vez de clic en "Analysis schedule". En está ventana defina un cronograma de analisis diario y de clic en save.

Figura XX: Definir un cronograma de análisis

CodeScene lanzará el analisis, teniendo en cuenta los componentes de arquitectura definidos, en la hora definida en el cronograma.

Visualizar analisis de arquitectura

Una vez corrido el analisis, usted podrá dirigirse al menú de "Architecture" y dar clic en "System Health"

Aqui verá una tabla con estadisticas sobre la salud del código para cada uno de los componentes definidos. La tabla nos mostrara cual es la salud del código promedio en los "Hotspots del componente", cual es la salud promedio para el componente en general, cuál es la salud del peor archivo dentro del componente y que tan familiarizados están los desarrolladores con el código dentro del componente.

Dirijase ahora al menú de "Hotspots", veremos una gráfica similar a la que vimos anteriormente en "Hotspots" para todo el sistema, con la diferencia que solo se resaltan los componentes definidos.

Dirijase ahora al menú de "Code Health", al igual que ocurrió para "Hotspots", la gráfica de Code Health nos mostrará la salud del código para los componentes de arquitectura definidos.

CodeScene es una herramienta de análisis de software que permite a los desarrolladores analizar código fuente para obtener visualizaciones sobre complejidad y calidad del software, además de brindar información sobre como evolucionan los componentes de código y como el conocimiento fluye durante el desarrollo. En nuestro caso nos sirve para entender el estado del codigo fuente y así tomar desiciones sobre partes del código que pueden necesitar refactorización, además de ayudarnos a entender cuales son los desarrolladores que tienen el conocimiento sobre cada parte del código fuente.

Versión 1.0

Kevin Sánchez, Kelly Garcés

Autores

Miguel Peña

Revisores