ALM Rangers

Implementando a análise de código estático com o StyleCop

Hamid Shahid

Com que frequência você encontra códigos incompreensíveis? Geralmente, formatação inconsistente, comentários inválidos e falta de convenções de nomenclatura que tornam o código ilegível. Essas inconsistências são frequentemente ignoradas como pequenas anomalias, mas elas podem fazer uma grande diferença na manutenção geral do código.

O StyleCop é uma excelente ferramenta para manter a consistência de estilo e formato em seu código-fonte. Da mesma maneira que a Análise de Código do Visual Studio, o StyleCop executa análise de código estático. Entretanto, diferente da Análise de Código do Visual Studio, ele examina os arquivos de código-fonte, em vez do código gerenciado. Além disso, o StyleCop faz a validação apenas de inconsistências de estilo e não executa otimização de código e verificações de desempenho.

Neste artigo, vou apresentar o StyleCop, mostrar como ele funciona e discutir quais fatores devem ser considerados ao adotá-lo em seu projeto. Por fim, demonstrarei como incluir a execução do StyleCop em sua compilação do Visual Studio Team Foundation Server (TFS).

Fundamentos do StyleCop

O StyleCop (stylecop.codeplex.com) é uma ferramenta de software livre que executa análise de código estático em arquivos de origem do C#. Ele é integrado ao Visual Studio e é exibido no menu de contexto, fornecendo a você a opção de examinar o arquivo atual ou qualquer arquivo ou projeto selecionado. A Figura 1 mostra as opções do StyleCop disponíveis no menu de contexto para um projeto do Visual Studio.

Figura 1 Opções do menu de contexto do StyleCop

Quando você seleciona a opção Run StyleCop ou Run StyleCop (Rescan All), o StyleCop analisa todos os arquivos C# e os valida para as regras designadas do StyleCop. Se existirem violações, um aviso será exibido na janela de lista de erros. 

Arquivo de configurações do StyleCop É aqui que o StyleCop mantém todas as suas opções de configuração. Esse arquivo contém informações como as regras selecionadas, informações de vocabulário, como acrônimos ou palavras personalizadas, e se o arquivo de configurações deve ser mesclado com o arquivo de configurações nos diretórios pai, se houver.

Como o StyleCop procura o arquivo de configurações recursivamente no diretório pai do arquivo de origem, é uma prática recomendada manter uma única versão do arquivo Settings.StyleCop. Manter um arquivo e armazená-lo na raiz do projeto da equipe garante que você use o mesmo conjunto de regras em todo o projeto da equipe.

Arquivo de dicionário personalizado Além de permitir a adição de palavras e acrônimos ao arquivo de configurações, o StyleCop também trabalha com um arquivo CustomDictionary.xml que usa o mesmo formato do dicionário de Análise de Código do Visual Studio. Isso permite que você use o mesmo arquivo de dicionário para ambos. A Figura 2 exibe o formato do arquivo de dicionário.

Figura 2 Arquivo de dicionário 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>

Tendo explicado a finalidade e os fundamentos do StyleCop, agora vou abordar o que está envolvido para torná-lo parte integral da prática de trabalho de sua equipe de desenvolvimento.

Regras do StyleCop Essa é uma verificação que o StyleCop executa em um arquivo de código. Existem várias regras disponíveis prontas para uso e, se desejar, você tem a opção de escrever suas próprias regras personalizadas. O wiki do StyleCop fornece detalhes sobre como escrever suas próprias regras do StyleCop (consulte bit.ly/12P665L).

A primeira etapa no uso do StyleCop é decidir quais regras do StyleCop devem ser usadas. Eu recomendo usar todas as regras do StyleCop. Entretanto, as equipes de desenvolvimento normalmente possuem seus próprios padrões de codificação e pode haver uma forte resistência quanto à adoção de determinadas regras do StyleCop. Você tem de balancear os benefícios a longo prazo de um código passível de manutenção e com estilo consistente em relação ao pequeno inconveniente que ele pode causar. Assim como muitas boas práticas, depois de se habituar com o uso do StyleCop, ele se torna comum. De qualquer maneira, é essencial concordar sobre as regras do StyleCop que a equipe usará em geral.

As regras do StyleCop se enquadram nas sete categorias a seguir:

1. Regras de documentação - Validam a adequação dos elementos de documentação nos arquivos de origem.
2. Regras de layout - Validam o layout e o espaçamento entre linhas nos arquivos de origem.
3. Regras de manutenção - Validam os arquivos de origem em relação aos aspectos de manutenção, como parênteses indesejados ou a existência de várias classes em um único arquivo.
4. Regras de nomenclatura - Validam a possibilidade de substituição de nomes de método e variável.
5. Regras de ordenação - Validam se conteúdo do código está ordenado corretamente.
6. Regras de legibilidade - Validam se o código está adequadamente formatado e legível.
7. Regras de espaçamento - Validam se o espaçamento no conteúdo do código é válido e apropriado.

Leia mais sobre as categorias do StyleCop e suas respectivas regras na documentação de regras do StyleCop em bit.ly/191GgiQ.

Adicionando o StyleCop ao seu Team Build

Está tudo certo em ter as regras do StyleCop selecionadas e armazenadas em um arquivo de configurações, mas a única maneira de garantir que o StyleCop seja executado de maneira consistente para todo o código-fonte é executá-lo como parte do processo de compilação.

Há duas formas de fazer isso:

1. Integrar o StyleCop ao arquivo do MSBuild do projeto C#, de forma que ele seja executado sempre que o projeto for compilado. A documentação do StyleCop (bit.ly/13ZX2xL) descreve como fazer isso.
2. Adicionar o StyleCop ao seu Team Build de integração contínua, de forma que ele seja executado em todos os check-ins.

Explicarei como executar o StyleCop em seu Team Build de integração contínua. Se estiver usando compilações restringidas, a execução do StyleCop garantirá que não será feito check-in de nenhum arquivo de código com violações. Caso contrário, a compilação interrompida ainda solicitará que você corrija as violações quando fizer check-in de código.

Para executar o StyleCop no Team Build, o processo deve ser chamado de uma atividade no fluxo de trabalho da compilação. Usarei a atividade do StyleCop de um projeto de software livre chamado Community TFS Build Extensions (tfsbuildextensions.codeplex.com). O Community TFS Build Extensions é um conjunto de bibliotecas que contém várias atividades de fluxo de trabalho reutilizáveis que você pode simplesmente arrastar e soltar em seu modelo de processo do Team Build.

Alterações no controlador de compilação A primeira coisa que você deve fazer antes de personalizar o Team Build é definir o caminho de assemblies personalizados de seu controlador de compilação. Esse é o local do qual os agentes de compilação carregam os assemblies para qualquer atividade personalizada que encontrarem no fluxo de trabalho da compilação.

Para adicionar assemblies personalizados, crie uma nova pasta em um local apropriado de seu projeto de equipe. Eu nomeei a nova pasta como Assemblies personalizados e a criei sob BuildProcessTemplate, logo abaixo da pasta raiz do projeto da equipe. Agora, faça check-in dos assemblies a seguir:

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

A próxima etapa é configurar seu controlador de compilação para usar esses assemblies. Para fazer isso:

1. Clique no link da compilação no Team Explorer. Clique em Ações e selecione Gerenciar Controladores de Compilação.
2. Na caixa de diálogo exibida, selecione o controlador de compilação e clique no botão Propriedades.
3. Na caixa de diálogo Propriedades do controlador de compilação, defina a propriedade "Caminho de controle de versão para assemblies personalizados" como a pasta de assemblies personalizados que foi criada anteriormente no projeto da equipe, conforme exibido na Figura 3.

Figura 3 Propriedades do controlador de compilação

Clique em OK e feche a caixa de diálogo de propriedades. Neste ponto, o controlador de compilação está configurado para carregar suas atividades personalizadas. A próxima etapa é personalizar o modelo de sua compilação.

Considerações sobre o StyleCop

Estas são algumas considerações que você deve saber:

• Diferente da Análise de Código do Visual Studio, o StyleCop não oferece suporte ao Visual Basic .NET e pode ser usado apenas para arquivos de origem escritos em C#.
• No momento em que este artigo foi escrito, o StyleCop ainda não estava disponível para o Visual Studio 2013.
• O Controlador de Compilação Hospedado é um controlador de compilação hospedado na nuvem pelo Visual Studio Team Foundation Service. As etapas para configurar esse controlador de compilação são as mesmas se você estiver usando um servidor de compilação local.
• Este artigo usou o Team Foundation Server (TFS) 2012. As etapas são as mesmas para o TFS 2010 e o TFS 2013. Certifique-se de que esteja usando a versão correta do TFS Build Extensions.

Modelos de compilação personalizados

Para cada novo projeto de equipe, o TFS cria vários modelos de compilação prontos para uso. Esses modelos de compilação são criados em uma pasta chamada ProcessBuildTemplates que reside na raiz do projeto de equipe. Comece fazendo uma cópia do modelo DefaultTemplate.11.1.xaml e personalizando-o para adicionar a atividade StyleCop. Eu fiz uma cópia do arquivo DefaultTemplate.11.1.xaml e a renomeei como CustomTemplate.xaml.

Para personalizar o fluxo de trabalho da compilação, você deverá adicionar as atividades personalizadas ao seu ambiente de desenvolvimento. Para fazer isso, crie um novo projeto de biblioteca de atividades de fluxo de trabalho no Visual Studio. Na caixa de diálogo Adicionar novo projeto, verifique se Microsoft .NET Framework 4.5 está selecionado como a plataforma de destino. A próxima etapa é adicionar um link para o arquivo CustomTem­plate.xaml no projeto recém-criado. Para fazer isso, clique com o botão direito do mouse no projeto, selecione Adicionar item existente, navegue até o arquivo CustomTemplate.xml e clique no botão Adicionar como vínculo.

A última etapa da configuração de seu ambiente de desenvolvimento é adicionar a atividade StyleCop à janela Caixa de Ferramentas para permitir as ações de arrastar e soltar. Para fazer isso, clique com o botão direito do mouse na área abaixo de “atividades” na janela Caixa de Ferramentas e selecione a opção Adicionar guia. Nomeie a nova guia como “TFS Build Extensions”. Clique com o botão direito do mouse no nome da guia e selecione “Escolher itens”. Vá até o assembly TfsBuildExtensions.Activities.Stylecop.dll e clique em OK. Agora, você pode abrir o arquivo CustomTemplate.xaml e arrastar a atividade StyleCop para ele.

Personalização do modelo de compilação Você deve executar o StyleCop no início do processo de compilação. Isso permite que a compilação falhe rapidamente se qualquer violação for encontrada. Como o StyleCop exige os arquivos de origem para fazer a verificação, o primeiro lugar em que o StyleCop pode ser executado é após a sequência Inicializar o Espaço de Trabalho dentro da sequência Executar no Agente, conforme mostrado na Figura 4.

Figura 4 Local de destino da atividade do StyleCop

Após determinar o local apropriado no fluxo de trabalho de compilação para adicionar a atividade do StyleCop, a próxima etapa é adicionar uma atividade de sequência. Renomeie a atividade de sequência para Executar StyleCop. A listagem final da minha sequência Executar StyleCop é mostrada na Figura 5.

Figura 5 Sequência Executar StyleCop

Código passo a passo A Figura 6 mostra os detalhes das variáveis definidas na sequência Executar StyleCop, seus tipos e suas respectivas finalidades.

Figura 6 Variáveis definidas na sequência Executar StyleCop

O fluxo de trabalho também contém um parâmetro chamado StyleCopSettingsFile do tipo String que armazena o caminho do arquivo de configurações do StyleCop.

A primeira atividade na sequência Executar StyleCop é a FindMatchingFiles. A atividade está no assembly Microsoft.TeamFoundation.Build.Workflow.dll e retorna a lista de todos os arquivos correspondentes ao padrão de arquivo fornecido. A Figura 7 descreve como as propriedades dessa atividade são definidas.

Figura 7 Propriedades da atividade FindMatchingFiles

A atividade é transmitida para o padrão de localizar todos os arquivos do C# (*.cs) no diretório de compilação e retorna o resultado na enumeração de SourceCodeFiles.

A próxima atividade da sequência é a ConvertWorkspaceItem, que reside no assembly Microsoft.TeamFounda­tion.Build.Workflow.Activities.dll. A atividade converte o caminho do servidor do arquivo de configurações do StyleCop específico — transmitido como um parâmetro — para um caminho local no servidor de compilação. As propriedades dessa atividade são exibidas na Figura 8.

Figura 8 Obter as propriedades do arquivo de configurações local

Agora que os nomes do arquivo de origem foram recuperados e a localização das configurações do StyleCop foi estabelecida, a próxima atividade na sequência Executar StyleCop é a StyleCop. A Figura 9 mostra como as propriedades da atividade StyleCop são definidas.

Figura 9 Executar as propriedades do StyleCop

A atividade obtém a enumeração de SourceCodeFiles — convertida em uma matriz — como entrada e retorna o resultado e a contagem de violações nas variáveis IsSuccess e ViolationCount, respectivamente. É fornecido o nome de exibição Executar StyleCop e é definido que os avisos devem ser tratados como erros e que a compilação deve falhar se for encontrado qualquer erro.

A atividade final na sequência Executar StyleCop é a atividade Escrever mensagem de compilação. A atividade é definida para exibir o resultado e a contagem de violações. A Figura 10 exibe como as propriedades dessa atividade são definidas.

Figura 10 Propriedades da atividade Escrever mensagem de compilação

O seu modelo de compilação personalizado está pronto para ser usado. Salve e faça check-in do arquivo CustomTemplate.xaml. Para usar o novo modelo de compilação, abra sua definição de compilação. clique no processo, expanda Modelo de processo de compilação e clique no botão Novo. Na caixa de diálogo de novo modelo de processo, escolha a opção para selecionar um arquivo XAML existente e navegue até o arquivo CustomTemplate.xaml.

Defina o valor do parâmetro StyleCopSettingsFile como o local de seu arquivo Settings.StyleCop. Clique em Salvar para salvar a definição de compilação. A sua compilação com o StyleCop agora está pronta para ser usada. É melhor usar esse modelo de compilação para suas compilações restringidas. Isso garantirá que nenhum dos arquivos de origem com check-in tenham qualquer violação do StyleCop.

Próximas Etapas

Eu demonstrei como você pode usar o StyleCop para impor a análise de código estático em seu Team Build. A análise de código estático promove padrões de codificação melhores e pode ser executada em seu Team Build para garantir que todo o código com check-in esteja de acordo com seus padrões. De maneira semelhante, você pode impor outras práticas recomendadas ao seu Team Build. O Microsoft ALM Rangers criou vários modelos de compilação úteis que você pode usar no projeto Team Foundation Build Customization Guide (vsarbuildguide.codeplex.com). Além disso, você tem a opção de escrever suas próprias atividades ou usar as atividades disponíveis no projeto Community TFS Build Extensions.

Hamid Shahid é um Microsoft ALM Ranger e consultor independente com mais de 12 anos de experiência em design e desenvolvimento de software empresarial. Ele tem muito interesse em promover as melhores práticas relacionadas às tecnologias Microsoft ALM. Para entrar em contato com ele, visite seu blog em hamidshahid.blogspot.com e pode ser seguido no Twitter em twitter.com/hamid_shahid.

Agradecemos aos seguintes ALM Rangers e especialistas técnicos pela revisão deste artigo: Mike Fourie (consultor independente), Willy-Peter Schaub (Microsoft) e Patricia Wagner (Microsoft)
Mike Fourie é consultor independente com mais de 13 anos de experiência em desenvolvimento de software, além de ser especialista em automação de compilação e implementação. Ele é um Microsoft ALM MVP e um ALM Ranger conceituado. Para contatá-lo, visite seu blog em freetodev.com. Você também pode segui-lo no Twitter, em twitter.com/mikefourie.

Willy-Peter Schaub é gerente de programas sênior da equipe Visual Studio ALM Rangers do Microsoft Canada Development Center. Desde meados da década de 1980, tem se empenhado em buscar a simplicidade e a facilidade de manutenção na engenharia de software. Leia seu blog em blogs.msdn.com/b/willy-peter_schaub e siga-o no Twitter em twitter.com/wpschaub.