Wednesday, September 10, 2014

Использование StyleCop

Начало

Многие программисты за свою карьеру успели поработать на проектах, которые разрабатываются не один год. И все представляют какие страшные вещи можно найти в проекте, процесс написания которого был плохо поставлен.

Все началось, что к нам на проект, очень похожий на вышеупомянутые, пришел Женя. Он уже работал со StyleCop, поэтому идея интеграции StyleCop в проект принадлежала ему.

Шаги для интеграции

1) Мы начали с того, что разработали руководство по написанию кода, в которое попытались включить лучшие практики, которые существуют в мире разработки .NET приложений. За основу были взяты C# Coding Conventions (C# Programming Guide), немного доработаны в связи со спецификой нашего проекта и утверждены большими дядями типа Principal Solution Developer =).

2) Установка и использование StyleCop. Скачать и установить StyleCop можно пройдя по ссылке http://stylecop.codeplex.com/



Установка завершилась успешно, теперь можно открыть Visual Studio и попробовать поработать со StyleCop. Для начала нам необходимо создать файл с настройками, по которым будет проходить валидация существующего кода. Выбираем "StyleCop Settings" нажав правой кнопкой по проекту.


После того, как мы выбрали "StyleCop Settings" перед нами появится окно, в котором можно будет выбрать правила, которые подходят для нашего проекта.



После того, как правила были выбраны, можно запусить StyleCop и проверить, удовлетворяет ли проект, выбранным правилам. Для этого необходимо выбрать файлы, которые вы желаете провалидировать и запустить StyleCop.



3) Более продвинутая настройка StyleCop в соответсвии с правилами написания кода, принятых на нашем проекте. 
Нам повезло, потому что нам не пришлось добавлять правила, которых не было в "коробке", поэтому для того, чтобы StyleCop валидация для нашего проекта проходила в соответсвии с нашими договоренностями по форматированию кода, мы удалили некоторые правила из стандартного набора. Файл с нашими настройками, можно скачать по ссылке Settings.StyleCop
Для того, чтобы применить данный файл к проекту, необходимо скопировать его в директорию, в которой находится файл проекта (*.sln)
Если ваш проект состоит из нескольких сборок и вы хотите, чтобы у вас был один файл со StyleCop настройками, в папку с проектом необходимо добавить файл Child Project Settings. В данном файле нужно указать путь к "Settings.StyleCop" файлу, который вы добавили в корень проекта.
Если случилось так, что набор предустановленных правил для вас не работает, StyleCop имеет возможность расширить набор правил. Узнать как это сделать можно по пройдя по ссылке: http://scottwhite.blogspot.com/2008/11/creating-custom-stylecop-rules-in-c.html

4) Как заставить программистов следовать правилам
StyleCop предоставляет возможность генерировать "Warning" или "Error" в случае, если код не соответсвует правилам. Мы долго спорили на тему, что же все таки лучше для нашего проекта и пришли к выводу, что "Warning" это хорошо, но данный подход не работает в большинстве случаев. Да и свалившийся билд подстегивает писать код красиво =). 
Для того, чтобы интегрировать StyleCop в процесс сборки проекта необходимо:
  1. Установить StyleCop.MSBuild. Данную операцию можно проделать через "Manage Nuget Pacakges" в Visual Studio.
  2. Добавить в файл проекта (*.csproj) свойство <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings>
<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
    ...    
    <AssemblyName>SampleProject</AssemblyName>
    <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings>
  </PropertyGroup>

Валидация существующих файлов

В нашем проекте было около 10 тысяч файлов, которые не удовлетворяли разработанным нами правилам. Приведение всех файлов к определенному формату могло занять кучу времени не только программистов, но и тестировщиков. Поэтому нам была необходима возможность постепенного изменения существующих файлов.
StyleCop предоставляет такую возможность. Более подробно можно прочитать в документации Using StyleCop on Legacy Projects. Для того, чтобы игнорировать валидацию для конкретного файла необходимо нажать правой кнопкой мыши по файлу и выбрать в меню "Exclude From StyleCop".


К сожаление данное решение работает только для выбранный файлов и является крайне неудобным, если в проекте их много.
Именно для такой ситуации команда StyleCop предоставляет небольшое приложение, которое может обновить файлы из указанного проекта. Скачать данное приложение можно по ссылке ExcludeFromStyleCop.

Заключение

StyleCop отличное средство для того, чтобы привести стиль написания исходного кода в порядок. На мой взгляд данное средство должно интегрироваться в проект со старта. Потом будет сложнее все поправить.




Wednesday, August 6, 2014

Правила настройки системы контроля доступа к исходному коду программы.

В проектах, над которыми работает большое количество людей, важно огранизовать работу таким образом, чтобы разработчики следовали определенному процессу в работе над исходным кодом.

Данное соответсвие может достигаться несколькими способами:
  1. Огранизационный. (Разработчики договариваются между собой, что они будут следовать определенному процессу)
  2. Технический. (Для системы контроля версий вводятся правила, которые не позволяют добавить код в систему, пока разработчик не выполнит все атрибуты процесса)
Основным приемуществом огранизационного подхода является простота реализации. Данный подход будет работать в относительно небольшой команде опытных разработчиков, которые никогда ничего не забывают и делают все правильно =). Утопично, не правда ли... ?!

Рассмотрим, второй способ, который на мой взляг является наиболее действенным в реальной жизни. Выделим правила, которым необходимо сделовать при настройке системы контроля доступа к исходным кодам.
  1. Не разрешать добавлять код, разработчик не указал комментарий к изменению. Комментарий должен быть понятным и отражать проделанную работу. Технически выполнить данное требование можно путем создания правила, которое будет запрещать добавлять код с пустым комментарием или с комментарием содержащим менее 5 слов.
  2. Добавление исходного кода должно быть привязано к задаче из списка задач для выполнения. К примеру это можно огранизовать в следующем виде:  
    • Создать определенный формат: Feature #(XXX): //Comment; Bug #(XXX): //Comment; etc;
    • Создавать ссылки на исходный код в системе контроля дефектов/задач. 
Возможны еще более делатальные настройки, которые будут специфичны для конкретного проекта, но на мой взгляд, указанные выше два правила должны быть в каждом проекте, если команда заботится о возможности отлеживания измений исходного кода.