ALM Rangers

Implementación de un análisis estático de código con StyleCop

Hamid Shahid

¿Cuántas veces se ha topado con código incomprensible? Usualmente son el formato incongruente, los comentarios incorrectos y falta de convenciones de nomenclatura que hacen que el código sea ilegible. A menudo, estas incongruencias pasan por alto como anomalías insignificantes, pero pueden tener un impacto importante en la facilidad de mantenimiento general del código.

StyleCop es una excelente herramienta para lograr que el código fuente conserve un estilo y formato coherente. Al igual que Visual Studio Code Analysis, StyleCop realiza un análisis estático del código. Sin embargo, a diferencia de Visual Studio Code Analysis, examina los archivos del código fuente en vez del código administrado. Además, StyleCop solo valida las incongruencias de estilo y no optimiza el código ni realiza pruebas de rendimiento.

En este artículo presentaré StyleCop, mostraré cómo funciona y analizaré los factores que hay que tener en cuenta al adoptarlo en un proyecto. Por último, demostraré cómo incluir la ejecución de StyleCop en la compilación de Visual Studio Team Foundation Server (TFS).

Aspectos básicos de StyleCop

StyleCop (stylecop.codeplex.com) es una herramienta de código abierto que realiza un análisis estático de código en los archivos de código fuente C#. Se integra en Visual Studio y aparece en el menú contextual, con la opción de examinar el archivo actual o cualquier conjunto de archivos o proyectos que queramos. En la figura 1 se muestran las opciones de StyleCop disponibles en el menú contextual de un proyecto en Visual Studio.

Figura 1 Opciones de StyleCop en el menú contextual

Al seleccionar la opción Run StyleCop o Run StyleCop (Rescan All), StyleCop analiza todos los archivos en C# y los valida con las reglas designadas de StyleCop. Si encuentra infracciones, aparece una advertencia en la ventana Error List. 

Archivo de configuración de StyleCop Esto es donde StyleCop conserva todas las opciones de configuración. Este archivo contiene información como las reglas seleccionadas, información sobre el vocabulario como palabras o acrónimos personalizados y si el archivo de configuración se debe combinar o no con el archivo de configuración de los directorios superiores, cuando los haya.

Dado que StyleCop busca el archivo de configuración en los directorios superiores del archivo de código fuente, el procedimiento recomendado es usar una sola versión del archivo Settings.StyleCop. Al mantener un solo archivo y conservarlo en la raíz del proyecto de equipo, podremos estar seguros de que se emplea el mismo conjunto de reglas en todo el proyecto del equipo.

Archivo de diccionario personalizado Además de permitir palabras adicionales y acrónimos en el archivo Settings, StyleCop también emplea un archivo CustomDictionary.xml que tiene el mismo formato del diccionario de análisis de código de Visual Studio. Esto permite usar el mismo diccionario en ambos casos. En la figura 2 se ilustra el formato del archivo de diccionario.

Figura 2 Archivo de diccionario personalizado

<Dictionary>
  <Words>
    <Unrecognized>
      <Word/>
    </Unrecognized>
    <Recognized>
      <Word/>
    </Recognized>
    <Deprecated>
      <Term PreferredAlternate=""/>
    </Deprecated>
    <Compound>
      <Term CompoundAlternate=""/>
    </Compound>
    <DiscreteExceptions>
      <Term />
    </DiscreteExceptions>
  </Words>
  <Acronyms>
    <CastingException>
      <Acronym />
    </CastingException>
  </Acronyms>
</Dictionary>

Ahora que expliqué el propósito y los aspectos básicos de StyleCop, recorreré los pasos necesarios para integrarlo en el proceso productivo del equipo de desarrollo.

Reglas de StyleCop Esta es una prueba que StyleCop realiza en un archivo de código fuente. Hay varias reglas disponibles listas para usar y también puede escribir sus propias reglas si lo desea. La wiki de StyleCop explica en detalle cómo escribir reglas personalizadas (consulte bit.ly/12P665L).

El primer paso al usar StyleCop es decidir las reglas que va a usar. Le recomiendo encarecidamente que use todas las reglas de StyleCop. Sin embargo, los equipos de desarrollo frecuentemente tienen sus propios estándares de codificación y podría haber una resistencia fuerte a la adopción de ciertas reglas de StyleCop. También debe contrapesar los beneficios a largo plazo de un código con un estilo congruente y fácil de mantener contra los pequeños inconvenientes que pudiera causar. Al igual que muchos procedimientos recomendados, una vez que adquiere el hábito de usar StyleCop, se convierte en algo natural. En cualquier caso, es imprescindible que todo el equipo se ponga de acuerdo sobre las reglas de StyleCop que van a emplear.

Lar reglas de StyleCop se dividen en las siguientes siete categorías:

1. Reglas de documentación: validan la idoneidad de los elementos de documentación en los archivos de código fuente.
2. Reglas de diseño: validan el diseño y el interlineado en los archivos de código fuente.
3. Reglas de facilidad de mantenimiento: validan los aspectos relacionados con la facilidad del mantenimiento, tales como paréntesis no deseados o la existencia de varias clases en un mismo archivo.
4. Reglas de nomenclatura: validan la factibilidad de sustituir los nombre de métodos y variables.
5. Reglas de orden: validan que el contenido del código se encuentre en el orden correcto.
6. Reglas de legibilidad: validan que el código tenga el formato adecuado y que sea legible.
7. Reglas de espaciado: validan que el espaciado en el contenido del código sea válido y adecuado.

Puede leer más sobre las diferentes categorías de StyleCop y sus respectivas reglas en la documentación sobre las reglas de StyleCop en bit.ly/191GgiQ.

Incorporación de StyleCop en Team Build

Seleccionar las reglas de StyleCop y almacenarlas en un archivo de configuración está muy bien, pero la única forma de garantizar que StyleCop se ejecute en forma sistemática para todo el código fuente es ejecutarlo como parte del proceso de compilación.

Tenemos dos maneras de hacer esto:

1. Integrar StyleCop con el archivo MSBuild del proyecto C# para que se ejecute cada vez que se compila el proyecto. La documentación de StyleCop (bit.ly/13ZX2xL) explica cómo hacerlo.
2. Agregar StyleCop a la integración continua de Team Build, para que se ejecute cada vez que se realiza una publicación.

Explicaré como ejecutar StyleCop en la integración continua de Team Build. Si no usa compilaciones con entradas validadas, la ejecución de StyleCop garantizará que cualquier archivo de código fuente no conforme no se publicará. Si no se usa en compilaciones validadas, la compilación de todas maneras le pedirá que corrija las inconformidades cuando publica el código.

Para ejecutar StyleCop en Team Build, el proceso se debe invocar desde una actividad en el flujo de trabajo de la compilación. Usaré la actividad StyleCop desde un proyecto de código abierto llamado Community TFS Build Extensions (tfsbuildextensions.codeplex.com). Community TFS Build Extensions es un conjunto de bibliotecas que contienen varias actividades de flujo de trabajo reutilizables que usted puede arrastrar y colocar simplemente en la plantilla de proceso de Team Build.

Cambios en el controlador de la compilación Lo primero que debe hacer antes de personalizar la compilación de Team Build es configurar la ruta de acceso personalizada de los ensamblados del controlador de la compilación. Desde esta ubicación, los agentes de compilación cargan los ensamblados para cualquier actividad personalizada que encuentran en el flujo de trabajo de la compilación.

Para agregar ensamblados personalizados, debe crear una carpeta nueva en un lugar adecuado en el proyecto de equipo de TFS. A la carpeta nueva le puse el nombre Custom Assemblies y la creé debajo de BuildProcessTemplate, justo debajo de la carpeta raíz del proyecto de equipo. Ahora publique los siguientes ensamblados:

• StyleCop.dll
• StyleCop.CSharp.dll
• StyleCop.CSharp.Rules.dll
• TFSBuildExtensions.Activities.dll
• TFSBuildExtensions.Activities.StyleCop.dll

El siguiente paso consiste en configurar el controlador de la compilación para que use estos ensamblados. Para esto:

1. Haga clic en el vínculo para compilar en Team Explorer. Haga clic en Acciones y seleccione Administrar controladores de compilación.
2. En el cuadro de diálogo que aparece, seleccione el controlador de compilación y haga clic en el botón Propiedades.
3. En el cuadro de diálogo Propiedades del controlador de compilación, establezca la propiedad “Ruta de acceso de control de versiones a ensamblados personalizados” a la carpeta Custom Assemblies que se creó previamente en el proyecto de equipo de TFS, tal como se aprecia en la figura 3.

Figura 3 Propiedades del controlador de compilación

Haga clic en Aceptar y cierre el cuadro de diálogo con las propiedades. Llegados a este punto, el controlador de compilación está configurado para cargar las actividades personalizadas. El siguiente paso es personalizar la plantilla de la compilación.

Consideraciones sobre StyleCop

Estas son algunas consideraciones que debe tener en cuenta:

• A diferencia de Visual Studio Code Analysis, StyleCop no es compatible con Visual Basic .NET y solo sirve para el código escrito en C#.
• En el momento de redactar este artículo, StyleCop no estaba disponible aún para Visual Studio 2013.
• El Controlador de compilación hospedado es un controlador de compilación hospedado en la nube por Visual Studio Team Foundation Service. Los pasos para configurar este controlador de compilación son los mismos que para usar el servidor de compilación local.
• Para este artículo se usó Team Foundation Server (TFS) 2012. Los pasos son los mismos para TFS 2010 y TFS 2013. Asegúrese de usar la versión correcta de las Extensiones de compilación de TFS.

Plantillas de compilación personalizadas

Para cada proyecto de equipo nuevo, TFS crea varias plantillas en forma automática. Estas plantillas de compilación se crean en una carpeta llamada ProcessBuildTemplates que reside en la raíz del proyecto de equipo. Comience por tomar una copia de la plantilla DefaultTemplate.11.1.xaml y personalizarla para agregar la actividad StyleCop. Yo creé una copia del archivo DefaultTemplate.11.1.xaml y le puse el nombre CustomTemplate.xaml.

Para personalizar el flujo de trabajo de la compilación, debe agregar las actividades personalizadas al entorno de desarrollo. Para esto, cree un nuevo proyecto de biblioteca de actividad de flujo de trabajo en Visual Studio. En el cuadro de diálogo Agregar nuevo proyecto, asegúrese de que Microsoft .NET Framework 4.5 esté seleccionado como la plataforma de destino. El siguiente paso es agregar un vínculo al archivo CustomTem­plate.xaml en el proyecto que recién creó. Para esto, haga clic con el botón secundario en el proyecto, seleccione Agregar elemento existente, busque el archivo CustomTemplate.xml y haga clic en el botón Agregar como vínculo.

El último paso para configurar el entorno de desarrollo es agregar la actividad StyleCop en la ventana Cuadro de herramientas para habilitar la función de arrastrar y colocar. Para esto, haga clic con el botón secundario en la zona debajo de “actividades” en la ventana Cuadro de herramientas y seleccione la opción Agregar pestaña. A la pestaña nueva, póngale el nombre “TFS Build Extensions”. Haga clic con el botón secundario en el nombre de la pestaña y seleccione “Elegir elementos”. Busque el ensamblado TfsBuildExtensions.Activities.Stylecop.dll y haga clic en Aceptar. Ahora puede abrir el archivo CustomTemplate.xaml y arrastrar la actividad StyleCop hasta allá.

Personalización de la plantilla de compilación Lo mejor es ejecutar StyleCop en las primeras etapas del proceso de compilación. Esto permite que la compilación se detenga rápidamente en caso de infracciones. Como StyleCop requiere examinar los archivos de código fuente, el primer lugar donde se puede ejecutar es después de la secuencia Inicializar espacio de trabajo, dentro de la secuencia Ejecutar en el agente, tal como se ilustra en la figura 4.

Figura 4 Ubicación de destino para la actividad StyleCop

Una vez que determinó la ubicación adecuada en el flujo de trabajo de compilación para agregar la actividad de StyleCop, el siguiente paso es agregar una actividad de secuencia. Cambie el nombre de la actividad de secuencia a Run StyleCop. El listado final de mi secuencia Run StyleCop se muestra en la figura 5.

Figura 5 Secuencia Run StyleCop

Recorrido por el código En la figura 6 se explican las variables definidas en la secuencia Run StyleCop, sus tipos y finalidades.

Figura 6 Variables definidas en la secuencia Run StyleCop

Nombre de la variable	Tipo	Descripción
SourceCodeFiles	IEnumerable<String>	Almacena los nombres de todos los archivos que debe examinar StyleCop.
IsSuccess	Boolean	Almacena si la actividad StyleCop detectó infracciones.
ViolationCount	Int32	Almacena la cantidad de infracciones de StyleCop.

El flujo de trabajo también contiene un parámetro llamado StyleCopSettingsFile del tipo String que almacena la ruta de acceso del archivo de configuración de StyleCop.

La primera actividad dentro de la secuencia Run StyleCop es FindMatchingFiles. La actividad se encuentra dentro del ensamblado Microsoft.TeamFoundation.Build.Workflow.dll y devuelve una lista con todos los archivos que coinciden con el patrón de archivo dado. La figura 7 describe cómo se configuran las propiedades de esta actividad.

Figura 7 Propiedades de la actividad FindMatchingFiles

Nombre de la propiedad	Valor
DisplayName	FindMatchingFiles
IsSuccess	String.Format(“{0}\**\*.cs”, BuildDirectory)
Result	SourceCodeFiles

La actividad recibe el patrón para encontrar todos los archivos C# (*.cs) en BuildDirectory y devuelve el resultado en la enumeración SourceCodeFiles.

La siguiente actividad en la secuencia es ConvertWorkspaceItem, que reside en el ensamblado Microsoft.TeamFounda­tion.Build.Workflow.Activities.dll. Esta actividad convierte la ruta de acceso del servidor del archivo Settings de StyleCop dado (que se pasa como parámetro) en una ruta local en el servidor de compilación. Las propiedades de esta actividad se muestran en la figura 8.

Figura 8 Propiedades de Get Local Settings File

Nombre de la propiedad	Valor
Direction	ServerToLocal
DisplayName	Get Local Settings File
Input	StyleCopSettingsFile
Result	StyleCopSettingsFileLocalPath
Workspace	Workspace

Ahora que se recuperaron los nombres de los archivos de código fuente y se estableció la ubicación de la configuración de StyleCop, la siguiente actividad en la secuencia Run StyleCop es la actividad StyleCop. En la figura 9 se muestran los valores de las propiedades de la actividad StyleCop.

Figura 9 Propiedades de Execute StyleCop

Nombre de la propiedad	Valor
DisplayName	Execute StyleCop
LogExceptionStack	True
SettingsFile	StyleCopSettingsFile
ShowOutput	True
SourceFiles	SourceCodeFiles.ToArray()
Result	StyleCopSettingsFileLocalPath
Succeeded	IsSuccess
TreatWarningsAsErrors	True

La actividad toma la enumeración SourceCodeFiles (convertida en matriz) como entrada y devuelve el resultado y el recuento de las infracciones en las variables IsSuccess y ViolationCount, respectivamente. Recibe el nombre para mostrar Execute StyleCop y se establece para que trate las advertencias como errores y que genere un error de compilación en caso de encontrar algún error.

La última actividad de la secuencia Run StyleCop es la actividad Write Build Message. La actividad se configura para que muestre el resultado y el recuento de infracciones. La figura 10 describe cómo se configuran las propiedades de esta actividad.

Figura 10 Propiedades de la actividad Write Build Message

Nombre de la propiedad	Valor
DisplayName	Completion Message
Importance	Microsoft.TeamFoundation.Build.Client.BuildMessageImportance.Normal
Message	String.Format(“StyleCop was completed with {0} violations”, StyleCopViolationsCount)

La plantilla de compilación Custom ahora está lista para usar. Guarde y publique el archivo CustomTemplate.xaml. Para usar la plantilla de compilación nueva, abra la definición de compilación, haga clic en procesar, expanda Plantilla de proceso de compilación y haga clic en el botón Nueva. En el cuadro de diálogo Nueva plantilla de proceso que aparece, seleccione la opción “Seleccionar un archivo XAML existente” y busque el archivo CustomTemplate.xaml.

Establezca el valor del parámetro StyleCopSettingsFile en la ubicación del archivo Settings.StyleCop. Haga clic en Guardar para guardar la definición de compilación. La compilación con StyleCop ahora está lista para usar. Lo mejor es usar esta plantilla de compilación para las compilaciones validadas. Esto garantizará que ninguno de los archivos de código fuente que se publicaron tengan infracciones de StyleCop.

Pasos siguientes

Demostré cómo usar StyleCop para llevar a cabo un análisis estático del código en la compilación de Team Build. El análisis estático de código promueve estándares de codificación mejores y se puede ejecutar en Team Build para garantizar que todo el código publicado respete los estándares. Asimismo, puede hacer cumplir otros procedimientos recomendados en Team Build. Los Microsoft ALM Rangers desarrollaron varias plantillas útiles que puede usar, en el proyecto Team Foundation Build Customization Guide (vsarbuildguide.codeplex.com). Además, tiene la opción de escribir sus propias actividades o usar las que están disponibles en el proyecto Community TFS Build Extensions.

Hamid Shahid es Microsoft ALM Ranger y consultor independiente con más de 12 años de experiencia en el diseño y desarrollo de software empresarial. Tiene un gran interés en los procedimientos recomendados en las tecnologías de Microsoft ALM. Puede ponerse en contacto con él a través de su blog en hamidshahid.blogspot.com y lo puede seguir en Twitter en twitter.com/hamid_shahid.

Gracias a los siguientes ALM Rangers y expertos técnicos por su ayuda en la revisión de este artículo: Mike Fourie (consultor independiente), Willy-Peter Schaub (Microsoft) y Patricia Wagner (Microsoft)
Mike Fourie es consultor independiente con más de 13 años de experiencia en el desarrollo de software y se especializa en la automatización de la compilación e implementación. Ha recibido las distinciones de Microsoft ALM MVP y Distinguished ALM Ranger. Puede ponerse en contacto con él a través de su blog en freetodev.com. También puede seguirlo en Twitter en twitter.com/mikefourie.

Willy-Peter Schaub es administrador en jefe de programas de los ALM Rangers de Visual Studio en el Centro de desarrollo canadiense de Microsoft. Desde mediados de la década de 1980, ha emprendido una búsqueda por la simplificación y el facilitamiento de mantención en la ingeniería de software. Puede leer su blog en blogs.msdn.com/b/willy-peter_schaub y seguirlo en Twitter en twitter.com/wpschaub.