Una de las mejoras que incluye Visual Studio Team System 2008 es el soporte para diccionarios propios en cuanto a la ejecución de las reglas de análisis de código estático se refiere. A pesar de que es una de las funcionalidades que aparece en la mayoría de las listas de nuevas características del producto no es del todo fácil encontrar información detallada acerca de como funciona.
Solo para refrescar un poco la memoria, os comento que el Análisis estático de código, es una funcionalidad que ofrece Visual Studio Team System desde la versión 2005 y que antes podíamos utilizar desde una herramienta externa llamada FxCop. Esta funcionalidad nos permite definir un conjunto de reglas que serán verificadas sobre nuestro código y que varían en cuanto a objetivo. Podemos encontrar reglas relacionadas con el rendimiento, el diseño de nuestras APIs, la portabilidad de nuestro código, mantenibilidad o el caso sobre el que me centraré en esta entrada, el nombrado de los elementos públicos de nuestro código, ya sean interfaces, clases, métodos o propiedades.
Visual Studio Team System viene acompañado de una serie de reglas de nombrado que podemos activar a voluntad y que van desde sugerirnos no utilizar guiones bajos o el correcto uso de mayúsculas y minúsculas, hasta que no usemos variables en los métodos con el mismo nombre que los miembros de una clase. Pero si prestamos atención a las reglas de nombrado (Naming Rules), estas nos sugieren muchas cosas relacionadas con los nombres que usamos para los elementos públicos de nuestro código y se basa en el diccionario de palabras de Word para realizar el análisis, aunque no es necesario tener Word instalado ya que dentro de la carpeta del Análisis estático de código viene incluido ya el diccionario. Sin embargo para los casos en los que este diccionario no sea suficiente se nos permite tener un diccionario personalizado de palabras contra el que el motor de Análisis estático de código realizará las comprobaciones necesarias.
Para añadir un diccionario personalizado lo único que tenemos que hacer es agregar un fichero Xml a nuestro proyecto y cambiar el valor de la propiedad Build Action del fichero y ponerlo a CodeAnalysisDictionary, de esta forma cuando se ejecute el análisis estático de código se verificarán la palabras contra el diccionario que acabamos de crear.
El fichero Xml tiene una estructura determinada y en él se nos permite añadir una lista de palabras validas, no validas, palabras en desuso y su alternativa actual, una lista de palabras compuestas, una lista de excepciones para palabras compuestas y por ultimo una lista de excepciones para acrónimos de palabras, aunque veremos cada uno de los puntos en detalle. Si queréis ver un fichero Xml completo bien formado y documentado os recomiendo que vayáis a la ruta «C:Program FilesMicrosoft Visual Studio 9.0Team ToolsStatic Analysis ToolsFxCop» donde podéis encontrar un fichero llamado «CustomDictionary.xml» que viene con el propio Visual Studio. A continuación os describo cada unos de los tipos de listas que podemos encontrar dentro de este fichero:
- Palabras reconocidas: Lista de palabras que a pesar de no estar en el diccionario interno no provocarán un error del tipo CA1704. Esta lista de palabras no es sensible a mayúsculas y minúsculas y debemos evitar añadir palabras compuestas en esta lista.
<?xml version="1.0" encoding="utf-8" ?>
<Dictionary>
<Words>
<Recognized>
<Word>accessor</Word>
<Word>accessors</Word>
<Word>acos</Word>
...
<Word>xsi</Word>
<Word>xsl</Word>
<Word>xslt</Word>
</Recognized>
</Words>
</Dictionary> - Palabras no reconocidas: Lista de palabras que a pesar de estar incluidas en el diccionario se quiere evitar su uso. Estas palabras, al igual que las reconocidas, no son sensibles a mayúsculas y minúsculas y debemos evitar introducir palabras en desuso en esta lista. En caso de que usemos alguna de las palabras incluidas en esta lista provocaremos que la reglas CA1704 genere un Warning o un Error en base a nuestra configuración.
<?xml version="1.0" encoding="utf-8" ?>
<Dictionary>
<Words>
<Unrecognized>
<Word>cb</Word>
<Word>ch</Word>
<Word>gt</Word>
<Word>idx</Word>
...
<Word>tw</Word>
<Word>val</Word>
</Unrecognized>
</Words>
</Dictionary> - Términos en desuso: La lista de términos en desuso, como cabe esperar, contiene una lista de palabras que no deberían usarse, pero además prove de una palabra alternativa que se debería usar. En caso de que una de las palabras de la lista este en nuestro código y sea de visibilidad pública hará que la regla CA1726 no sea valida. Los términos de esta lista no son sensibles a mayúsculas y minúsculas, pero la palabra alternativa sugerida debería tener una nomenclatura Pascal-Case y en caso de que no tengamos palabra sugerida simplemente podremos dejarla en blanco.
<?xml version="1.0" encoding="utf-8" ?>
<Dictionary>
<Words>
<Deprecated>
<Term PreferredAlternate="EnterpriseServices">complus</Term>
<Term PreferredAlternate="Canceled">cancelled</Term>
<Term PreferredAlternate="Indexes">indices</Term>
<Term PreferredAlternate="LogOn">login</Term>
<Term PreferredAlternate="LogOff">logout</Term>
<Term PreferredAlternate="SignIn">signon</Term>
<Term PreferredAlternate="SignOut">signoff</Term>
<Term PreferredAlternate="">flag</Term>
<Term PreferredAlternate="">flags</Term>
</Deprecated>
</Words>
</Dictionary> - Palabras compuestas: La lista de palabras compuestas y la alternativa asociada es usada por la regla CA1702 y el motivo de esta lista es que aun siendo palabras compuestas existen en el diccionario como palabras únicas pero sin embargo deberían ser usadas como dos palabras con el correspondiente uso de mayúsculas y minúsculas. Por ejemplo la palabra «Filename» existe en el diccionario, pero el uso correcto tratándose de código debería ser «FileName». Cualquier palabra que se encuentre en esta lista es automaticamente añadida a la lista de palabras DiscreteExceptions que veremos a continuación, ya que si no estuviesen añadidas nunca llegarían a generar un error y no se podría sugerir la alternativa correspondiente.
<?xml version="1.0" encoding="utf-8" ?>
<Dictionary>
<Words>
<Compound>
<Term CompoundAlternate="AutoScrolls">autoscrolls</Term>
<Term CompoundAlternate="AutoComplete">autocomplete</Term>
<Term CompoundAlternate="AutoCompletes">autocompletes</Term>
<Term CompoundAlternate="AutoSave">autosave</Term>
<Term CompoundAlternate="AutoSaves">autosaves</Term>
<Term CompoundAlternate="JavaScript">javascript</Term>
<Term CompoundAlternate="JScript">jscript</Term>
</Compound>
</Words>
</Dictionary> - Excepciones discretas: Como he comentado anteriormente, en esta lista se encuentran las palabras que a pesar de estar en el diccionario son palabras compuestas y dado que las listas no diferencian entre mayúsculas y minúsculas, se añaden en esta lista las palabras para que la regla CA1702 no genere un falso positivo y sugiera al usuario cambiar la «AutoComplete» por la palabra «AutoComplete».
<?xml version="1.0" encoding="utf-8" ?>
<Dictionary>
<Words>
<DiscreteExceptions>
<Term>onset</Term>
<Term>inset</Term>
<Term>byname</Term>
<Term>setout</Term>
<Term>countertype</Term>
</DiscreteExceptions>
</Words>
</Dictionary> - Acrónimos: Por último, si bien las listas anteriores eran listas de palabras, esta lista es de acrónimos. En ella incluiremos abreviaturas que por un motivo u otro no deban seguir las reglas de nombrado estándares, como por ejemplo el acrónimo del número matemático «Pi», que según los estándares de nombrado al ser de dos letras debería ir en mayúsculas, como «IO» por ejemplo.
<?xml version="1.0" encoding="utf-8" ?>
<Dictionary>
<Acronyms>
<CasingExceptions>
<Acronym>Pi</Acronym>
<Acronym>Na</Acronym> <!-- NaN -->
<Acronym>NESW</Acronym> <!-- North East South West -->
<Acronym>NWSE</Acronym> <!-- North West South East -->
</CasingExceptions>
</Acronyms>
</Dictionary>
Creo que con esto os podéis hacer una idea de la potencia que tienen estos diccionarios personalizados pero como aún me quedan algunas cosas que contar que os pueden resultar interesantes he decidido hacer una segunda parte de este post donde hablaré de como compartir un diccionario entre proyectos y de como dar soporte a la edición de estos ficheros.
