sergey_russkih89 Dec 1 2015 at 12:52

Рекомендации по написанию кода на C# от Aviva Solutions

40 min

79K

Представляю вашему вниманию перевод документа "Coding Guidelines for C# 3.0, 4.0 and 5.0".

Целью создания этого списка правил является попытка установить стандарты написания кода на C#, которые были бы удобными и практичными одновременно. Само собой, мы практикуем то, что создали. Эти правила являются одним из тех стандартов, которые лежат в основе нашей ежедневной работы в AvivaSolutions. Не все эти правила имеют четкое обоснование. Некоторые из них просто приняты у нас в качестве стандартов.

Статический анализатор кода VisualStudio (который также известен как FxComp) и StyleCop могут автоматически применять многие из правил кодирования и оформления путем анализа скомпилированных сборок. Вы можете сконфигурировать их таким образом, чтобы анализ производился во время компиляции или был неотъемлемой частью непрерывной или ежедневной сборки. Этот документ просто добавляет дополнительные правила и рекомендации, но его вспомогательный сайт www.csharpcodingguidelines.com предоставляет список правил анализа кода, необходимых в зависимости от того, с какой базой кода вы работаете.

Зачем мне это использовать?

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

На то, чтобы разобраться в коде уходит в 10 раз больше времени, чем на то, чтобы его изменить
Не каждый разработчик знает о тонкостях использования основных конструкций в C#
Не каждый знает о том, каких соглашений .NET Framework следует придерживаться, например, при использовании IDisposable или LINQ с его отложенным исполнением
Не каждый знает, как частные решения какой-либо задачи могут повлиять на производительность, безопасность, поддержку нескольких языков и т.д.
Не каждый разработчик сможет понять красивый, но абстрактный код другого разработчика

Базовые принципы

Имеется много неочевидных вещей, с которыми я сталкивался в моей работе в качестве консультанта и которые заслуживают упоминания как минимум в одной рекомендации по написанию кода. К сожалению, объем этого руководства должен находиться в разумных пределах. Однако, чтобы ни подумали некоторые начинающие разработчики, если я что-то не упомянул в этом документе, это не значит, что это не заслуживает внимания.

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

The Principle of Least Surprise. «Правило наименьшего удивления». Вы должны выбирать наиболее очевидное решение для своих задач, чтобы не сбить с толку других разработчиков и сделать код более понятным
Keep It Simple Stupid (или KISS). Дословно – «Делай это проще, тупица». Этот принцип гласит, что для решения поставленных задач необходимо выбирать наиболее простое решение
You Ain’t Gonne Need It (или YAGNI). «Вам это не понадобится». Он гласит: «Работайте над решением текущих задач, не пишите код только потому, что думаете, будто он пригодится вам в дальнейшем (вы можете предсказывать будущее?)»
Don’t Repeat Yourself (или DRY). «Не повторяйся». Этот принцип призывает вас воздержаться от дублирования кода и при этом не забыть об «эвристическом правиле трех»

Несмотря на то, что код может выглядеть очень неплохо, посмотрите, понятен ли он для других разработчиков, имеет ли он то поведение, которое от него следует ожидать, не пытается ли он решить те задачи, которые, возможно, возникнут в будущем. Если это не так, то стоит задуматься о рафакторинге.

Как мне начать?

Попросите всех разработчиков внимательно прочитать этот документ хотя бы один раз. Это должно дать им понимание того, какие принципы в нем содержатся
Убедитесь, что всегда имеются под рукой несколько печатных копий кратких ссылок на данное руководство
Включите наиболее значимые правила в ваш Project Checklist, на соответствие оставшимся правилам делайте проверку во время Peer Review
Решите, какие правила статического анализа применимы к вашему проекту и напишите их где-то. Например, опубликуйте их на вашем командном TFS сайте или создайте стандартный набор правил Visual Studio
Пополните настраиваемый словарь анализа кода терминами, именами и понятиями, специфичными для вашей компании или области деятельности. Если вы этого не сделаете, статический анализатор будет выводить предупреждения на конструкции, которые не будут включены в его внутренний словарь
Настройте VisualStudio выполнять проверку на следование выбранным правилам статического анализа в качестве части релизной сборки. Тогда они не будут служить помехой при разработке и отладке, но могут быть запущены при переключении на релизную конфигурацию
Добавьте в чеклист проекта пункты проверки на следование рекомендациям, чтобы быть уверенным, что весь новый код им соответствует, или используйте соответствующую политику чекинов, если вы хотите, чтобы любой код проверялся на соответствие правилам перед отправкой в репозиторий
ReSharper имеет интеллектуальный инспектор кода, который при некоторой настройке уже поддерживает многие требования данного руководства. Он будет автоматически выделять любой код, который не соответствует правилам именования (например, стиль именования паскаль или верблюжья нотация), находить мертвый код и делать любые другие проверки. Одного клика мыши (или сочетания горячих клавиш) будет достаточно для того, чтоб исправить это
ReSharper, кроме всего прочего, имеет окно File Structure, которое дает общее представление о членах вашего класса или интерфейса и позволяет вам легко перемещать их с помощью простого перетаскивания
Используя GhostDoc, вы можете генерировать XML комментарии, используя сочетания горячих клавиш. Вся прелесть заключается в том, что это позволяет точно следовать стилю MSDN документации. Тем не менее, не злоупотребляйте этим инструментом и используйте его только в качестве стартового

Почему вы создали это?

Идея пришла в 2002 году, когда Вику Харторгу (Philips Medical System) и мне была поставлена задача написания стандартов кодирования для C# 1.0. С того времени я регулярно добавлял, удалял и изменял правила, основываясь на опыте, отзывах коллег и новых плагинах, представленных в Visual Studio 2010. Кроме того, после прочтения книги Роберта Мартина «Чистый код: Создание, анализ и рефакторинг» я загорелся его идеями и решил включить некоторые из них в качестве правил. Хочу заметить, что этот документ ни в коем случае не является заменой его книги. Я искренне рекомендую прочесть его книгу, чтобы твердо усвоить принципы, лежащие в основе его рекомендаций. К тому же я решил дополнить принципы написания кода некоторыми принципами проектирования. Они являются слишком важными, чтобы их игнорировать, и имеют большое влияние на достижение высокого качества кода.

Эти рекомендации являются стандартами?

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

Чтобы помочь вам в выборе, я присвоил степень важности каждой рекомендации:

— Правило, которым вы никогда не должны пренебрегать и которое применимо ко всем ситуациям.

— Настоятельно рекомендуется соблюдать это правило.

— Рекомендуется соблюдать это правило, но оно применимо не ко всем ситуациям.

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

Обратная связь и отказ от ответственности

Этот документ был составлен во многом благодаря большому вкладу членов сообщества, статьям в блогах, онлайн дискуссиям и многим годам разработки на С#. Если у вас есть вопросы, замечания и предложения пишите мне на адрес dennis.doomen@avivasolutions.nl или в твиттер http://twitter.com/ddoomen. Я буду пытаться регулярно пересматривать и переопубликовывать этот документ в соответствии с новыми идеями, опытом и замечаниями.

Хочу отметить, что эти рекомендации лишь отражают мое видение правильного кода на C#. Aviva Solutions не несет ответственности за любые прямые или косвенные убытки, вызванные применением стандартов, описанных в данном документе.
Разрешается копировать, адаптировать и распространять этот документ и краткие ссылки на это руководство в некоммерческих целях и для внутреннего использования. Но вы не можете распространять этот документ, публиковать или распространять любые адаптированные копии данного документа в коммерческих целях без предварительного получения письменного разрешения от Aviva Solutions.

Различные рекомендации по проектированию

AV1200 Генерируйте исключение вместо возвращения статусного сообщения

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

AV1202 Обеспечьте полное и осмысленное сообщение об исключении

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

AV1205 Генерируйте настолько специфичное исключение, насколько это возможно

Например, если метод принял в качестве входного параметра null, следует сгенерировать ArgumentNullException вместо ArgumentException — его базового типа.

AV1210 Не игнорируйте ошибку путем обработки общих исключений

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

AV1215 Обрабатывайте исключения в асинхронном коде должным образом

Когда вы генерируете или обрабатываете исключения в коде, который использует async/await или Task, помните о следующих двух правилах:

Исключения, которые возникают в пределах блоков async/awaitи внутри Task, распространяются на задачу, которая ожидает выполнение этих блоков
Исключения, которые возникли в коде, предшествующем async/await и Task, распространяются на вызывающий код

AV1220 Всегда проверяйте делегат обработчика события на null

Событие, которое не имеет подписок, равно null. Таким образом, перед тем, как оно будет вызвано, убедитесь, что список делегатов, представляющих это событие, не равен null. Кроме того, чтобы избежать конфликтов при изменении из параллельных потоков, используйте временную переменную, чтобы избежать одновременного изменения.

event EventHandler<NotifyEventArgs> Notify; 

void RaiseNotifyEvent(NotifyEventArgs args) 
{ 
    EventHandler<NotifyEventArgs> handlers = Notify; 
    if (handlers != null) 
    { 
        handlers(this, args);    
    } 
}

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

event EventHandler<NotifyEventArgs> Notify = delegate {};

AV1225 Для обработки каждого события используйте защищенный виртуальный метод

Выполнение этой рекомендации позволит производным классам обрабатывать событие базового класса путем переопределения защищенного метода. Название защищенного виртуального метода должно быть таким же, как название события, но с префиксом On. Например, защищенный виртуальный метод для события с названием TimeChanged должен быть назван OnTimeChanged.

Примечание: От производных классов, которые переопределяют защищенный виртуальный метод, не требуется вызывать реализацию базового класса. Базовый класс должен продолжать свою работу корректно, даже если его реализация не вызвана.

AV1230 Использование событий уведомления об изменении свойств

Событие уведомления об изменении свойства должно иметь название наподобие PropertyChanged, где Property должно быть изменено на название свойства, с которым связано это событие.

Примечание: Если ваш класс имеет множество свойств, которые требуют соответствующих событий, попробуйте реализовать вместо этого интерфейс INotifyPropertyChanged. Он часто используется в паттернах Presentation Model и Model-View-ViewModel.

AV1235 Не отправляйте null в качестве аргумента при вызове события

Зачастую обработчик событий используется для обработки схожих событий от множества отправителей. В таком случае передаваемый аргумент используется для того, чтобы передать контекст вызова события. Всегда отправляйте ссылку на контекст (обычно this) при вызове события. Кроме того, не отправляйте null при вызове события, если оно не имеет данных. Если событие не имеет данных, отправьте EventArgs.Empty вместо null.

Исключение: Для статических событий передаваемый аргумент должен быть null.

AV1240 Используйте общие ограничения, если возможно

Вместо приведения и преобразования типа из конкретного в общий и наоборот используйте ключевое слово where или оператор as, чтобы привести объект к конкретному типу. Например:

class SomeClass 
{}  

// Неправильно
class MyClass<T> 
{ 
    void SomeMethod(T t) 
    { 
        object temp = t; 
        SomeClass obj = (SomeClass) temp; 
    } 
} 
 
// Правильно
class MyClass<T> where T : SomeClass 
{ 
    void SomeMethod(T t) 
    { 
        SomeClass obj = t; 
    } 
}

AV1250 Вычисляйте результат LINQ-запроса до того, как вернуть его

Посмотрите на следующий код:

public IEnumerable<GoldMember> GetGoldMemberCustomers() 
{ 
    const decimal GoldMemberThresholdInEuro = 1000000;  
    var q = from customer in db.Customers 
            where customer.Balance > GoldMemberThresholdInEuro 
            select new GoldMember(customer.Name, customer.Balance);  
    return q;          
}

Поскольку LINQ-запросы используют отложенное выполнение, возвращение q, как это ни странно, вернет древо выражения, представляющее вышеуказанный запрос. Всякий раз, когда пользователь вычисляет результат, используя foreach или что-то похожее, весь запрос выполняется заново, создавая каждый раз новые экземпляры GoldMember. Как следствие, вы не сможете использовать оператор ==, чтобы сравнить различные экземпляры GoldMember. Вместо этого всегда явно вычисляйте результат LINQ-запроса, используя ToList(), ToArray() или схожие методы.

Рекомендации по улучшению сопровождаемости кода

AV1500 В методе не должно быть более 7 объявлений

Метод, который включает в себя более 7 объявлений, скорей всего делает слишком много или берет на себя слишком большую ответственность. Кроме того, человеческая память требует, чтобы метод был коротким. Она не в состоянии удерживать в себе одновременно большее количество вещей, чтобы точно проанализировать и понять, что делает тот или иной кусок кода. Разделите метод на несколько маленьких, имеющих четкое предназначение, и дайте им имена, которые будут точно указывать на то, что они делают. При этом обратите внимание на то, чтобы алгоритм работы этой части программы оставался ясен для понимания.

AV1501 Создавайте все члены класса private, а типы internal по умолчанию

Чтобы принять более взвешенное решение о том, какие элементы должны быть доступны другим классам, в первую очередь как можно больше ограничьте их область видимости. Затем тщательно подумайте, какие члены или типы действительно стоит сделать public.

AV1502 Избегайте двойного отрицания

Несмотря на то, что такое свойство, как customer.HasNoOrder имеет право на существование, избегайте его использования с отрицанием. Например:

bool hasOrders = !customer.HasNoOrders;

Двойное отрицание более сложно для понимания, чем простое выражение, и люди склонны путаться в нем.

AV1505 Наименование сборки в ее названии должно идти после наименования ее пространства имен

Все DLL должны именоваться в соответствии с паттерном Company.Component.dll, где Company — это название вашей фирмы, а Component — наименование одного или более пространства имен, разделенных точками. Например:

AvivaSolutions.Web.Controls.dll

В качестве примера можно привести объединение группы классов в пространстве имен AvivaSolutions.Web.Binding, которое включает в себя некая сборка. Согласно данной рекомендации эта сборка должна быть названа AvivaSolutions.Web.Binding.dll.

Исключение: Если вы решите связать классы из различных несвязанных пространств имен в одну сборку, добавьте суффикс Core к ее названию. Однако не используйте этот суффикс в названиях пространств имен. Например: AvivaSolutions.Consulting.Core.dll.

AV1506 Называйте файлы с исходным кодом в соответствии с тем типом данных, который он содержит

Используйте нотацию паскаль для именования файлов и не используйте подчеркивания.

AV1507 Ограничивайте содержимое файла с исходным кодом одним типом данных

Исключение: Вложенные типы, по понятным причинам, должны быть частью того же самого файла.

AV1508 Наименование файла с исходным кодом, который содержит частичный тип данных, должно отражать назначение этой части

Когда используются частичные типы и идет разделение частей на файлы, имя каждого файла должно быть логически разделено на две части. Первая часть – название типа. Вторая – роль, которую данный фрагмент играет в типе. Например:

// В файле MyClass.cs 
public partial class MyClass 
{...} 
  
// В файле MyClass.Designer.cs 
public partial class MyClass 
{...}

AV1510 Используйте using вместо указания полной ссылки на тип из другого пространства имен

Не используйте полную ссылку на тип из другого пространства имен в целях предотвращения конфликтов именования. Например, не делайте так:

var list = new System.Collections.Generic.List<string>();

Лучше сделать так:

using System.Collections.Generic; 
var list = new List<string>();

Если вам необходимо избежать конфликтов именования, используйте директиву using для создания псевдонима пространства имен или типа:

using Label = System.Web.UI.WebControls.Label;

AV1515 Не используйте «магические» числа

Не используйте литеральные значения, числа или строки в вашем коде ни для чего другого, кроме как для объявления констант. Для примера:

public class Whatever
{
    public static readonly Color PapayaWhip = new Color(0xFFEFD5);
    public cons tint MaxNumberOfWheels = 18;
}

Строки, предназначенные для логирования или трассировки, являются исключением из этого правила. Литеральные значения допускается использовать только тогда, когда их смысл ясен из контекста и их не планируется изменять. Например:

mean = (a + b) / 2; // среднее арифметическое
WhaitMilliseconds(waitTimeInSeconds * 1000); // тут тоже все понятно

Если значение одной константы зависит от значения другой, укажите это в своем коде.

public class SomeSpecialContainer
{
    public const int MaxItems = 32;
    public const int HighWaterMark = 3 * MaxItems / 4;     // 75%
}

Заметка: Перечисления часто могут использоваться в качестве хранилища символьных констант.

AV1520 Используйте var только тогда, когда тип переменной очевиден

Используйте var только в том случае, если переменной присваивается результат LINQ-запроса или если тип переменной очевиден и использование var повысит читаемость кода. Например, так делать не стоит:

var i = 3;                                 // Что за тип? int? uint? float?
var myfoo = MyFatoryMethod.Create(“arg”);  // Не понятно, какой тип имеет 
					   // класс или интерфейс. Кроме того,
					   // тяжело изменять код, который работает 
					   // c этой переменной, если исходный класс
					   // вам недоступен

Вместо этого используйте var как в примерах ниже:

var q = from order in orders where order.Items > 10 and order.TotalValue > 1000; 
var repository = new RepositoryFactory.Get<IOrderRepository>(); 
var list = new ReadOnlyCollection<string>();

Во всех трех примерах тип присваиваемых переменным значений очевиден. Для получения более подробной информации об использовании var читайте статью Ерика Липперта «Использование и злоупотребления неявной типизацией».

AV1521 Объявляйте и инициализируйте переменные как можно позже

Избегайте стиля языков C и VisualBasic, когда все переменные объявляются в начале блока. Объявляйте и инициализируйте каждую переменную только тогда, когда она необходима.

AV1522 Присваивайте значение каждой переменной в отдельном объявлении

Никогда не делайте так:

var result = someField = GetSomeMethod();

AV1523 Предпочитайте инициализаторы объектов и коллекций раздельной установке свойств и раздельному добавлению новых объектов в коллекцию

Вместо такой конструкции:

var startInfo = new ProcessStartInfo(“myapp.exe”);
startInfo.StandardOutput = Console.Output; 
startInfo.UseShellExecute = true;

Используйте инициализатор объекта:

var startInfo = new ProcessStartInfo(“myapp.exe”) 
{ 
    StandardOutput = Console.Output, 
    UseShellExecute = true 
};

Вместо создания коллекции — таким образом:

var countries = new List<string>(); 
countries.Add(“Netherlands”); 
countries.Add(“United States”);

Используйте инициализатор коллекции:

var countries = new List<string> { “Netherlands”, “United States” };

AV1525 Не производите явного сравнения с true или false

Сравнение логического значения с true или false – это, как правило, плохой стиль программирования. В качестве примера:

while (condition == false)  // неправильно, плохой стиль 
while (condition != true) // тоже неправильно 
while (((condition == true) == true) == true) // где ты остановишься? 
while (condition) // OK

AV1530 Не изменяйте переменную цикла for или foreach внутри тела цикла

Обновление переменной цикла внутри тела цикла ведет к тому, что код становится запутанным. Особенно, если переменная изменяется более чем в одном месте. Это правило также относится к циклу foreach, хотя после окончания итерации енумератор обнаружит изменение коллекции и выдаст исключение.

for (int index = 0; index < 10; ++index) 
{ 
    if (some condition)  
    { 
        index = 11; // Неправильно! Вместо этого используйте ‘break’ или ‘continue’. 
    }  
}

AV1532 Избегайте вложенных циклов

Методы, содержащие вложенные циклы, более сложны для понимания, чем те, которые содержат только один цикл. По факту, в большинстве случаев циклы могут быть заменены гораздо меньшим по размеру LINQ-запросом, который использует ключевое слово from два раза и более для объединения данных.

AV1535 Всегда используйте конструкции if, else, while, for, foreach и case с фигурными скобками

Пожалуйста, обратите внимание, что это также поможет избежать возможной путаницы с конструкциями вроде этой:

if (b1) if (b2) Foo(); else Bar();  // к какому ‘if’ относится ‘else’?

Лучше сделать так:

if (b1) 
{ 
    if (b2) 
    { 
        Foo(); 
    } 
    else 
    { 
        Bar(); 
    } 
}

AV1536 Всегда используйте блок default в конце конструкции switch/case

Если блок default будет пуст, добавьте поясняющий комментарий. Кроме того, если этот блок не должен быть достижимым, сгенерируйте при его вызове InvalidOperationException, чтобы обнаружить будущие изменения, при которых ни один из блоков case не будет достигнут. Следование этой рекомендации позволит вам писать более чистый код, потому что все сценарии выполнения уже были продуманы.

void Foo(string answer) 
{ 
    switch (answer) 
    { 
        case "no": 
            Console.WriteLine("You answered with No"); 
            break; 
    
        case "yes": 
            Console.WriteLine("You answered with Yes"); 
            break; 
 
        default: 
            // Not supposed to end up here. 
            throw new InvalidOperationException("Unexpected answer " + answer); 
   } 
}

AV1537 Заканчивайте каждый блок if-else-if объявлением else

Например:

void Foo(string answer) 
{ 
    if (answer == "no") 
    { 
        Console.WriteLine("Вы ответили Нет"); 
    } 
    else if (answer == "yes") 
    { 
        Console.WriteLine("Вы ответили Да"); 
    } 
    else 
    { 
        // Что должно случиться, когда этот блок выполнится? Игнорировать это? 
        // Если нет, то  сгенерировать исключение InvalidOperationException. 
     } 
}

AV1540 Старайтесь избегать нескольких объявлений return

Один вход — одна точка выхода, так звучит этот принцип. Он позволяет поддерживать понятным ход выполнения метода. При этом если метод очень маленький и соответствует рекомендации AV1500, тогда несколько объявлений return могут быть актуальными и улучшат читаемость кода. Например, если метод возвращает логическое значение, удобней использовать два объявления return вместо логической переменной, которую вернет метод и которой будут присваиваться значения по ходу его выполнения.

AV1545 Не используйте блок if-else вместо простого (условного) присваивания

Выражайте свои намерения прямо. Например, вместо этого:

bool pos;
if (val > 0) 
{ 
    pos = true; 
} 
else 
{ 
    pos = false; 
}

Делайте так:

bool pos = (val > 0);   // инициализация

Вместо:

string result; 
if (someString != null) 
{ 
    result = someString; 
} 
else 
{ 
    result = “Unavailable”; 
}

Пишите:

return someString ?? “Unavailable”;

AV1547 Инкапсулируйте сложное выражение в методе или свойстве

Рассмотрим следующий пример:

if (member.HidesBaseClassMember && (member.NodeType != NodeType.InstanceInitializer)) 
{ 
    // что-то делаем
}

Чтобы понять, что делает этот код, вам придется вникать в его детали и предвидеть все варианты его выполнения. Конечно, вы можете добавить поясняющий комментарий перед этим кодом, но лучше замените сложное выражение методом, название которого будет говорить само за себя.

if (NonConstructorMemberUsesNewKeyword(member)) 
{ 
    // что-то делаем
}
 
private bool NonConstructorMemberUsesNewKeyword(Member member) 
{ 
 	return  
            (member.HidesBaseClassMember &&  
    	    (member.NodeType != NodeType.InstanceInitializer) 
}

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

AV1551 Вызывайте наиболее перегруженный метод из других перегрузок

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

public class MyString 
{ 
    private string someText;  
    public MyString(string text) 
    { 
        this.someText = text; 
    } 

    public int IndexOf(string phrase) 
    { 
        return IndexOf(phrase, 0, someText.Length); 
    } 

    public int IndexOf(string phrase, int startIndex) 
    { 
        return IndexOf(phrase, startIndex, someText.Length - startIndex ); 
    } 
 	
    public virtual int IndexOf(string phrase, int startIndex, int count) 
    { 
        return someText.IndexOf(phrase, startIndex, count); 
    } 
}

Класс MyString обеспечивает три перегрузки метода IndexOf, при этом две их них просто вызывают другую с большим количеством параметров. Заметьте, что это правило применимо к конструкторам класса. Реализуйте наиболее перегруженный конструктор и вызывайте его из других перегрузок, используя оператор this(). Также следует отметить, что параметры с одними и теми же именами должны следовать в одном и том же порядке во всех перегрузках.

Важно: Если вы хотите, чтобы поведение классов можно было менять с помощью переопределения данных методов, то объявите наиболее перегруженный метод как protected virtual, который вызывается всеми перегрузками.

AV1553 Используйте необязательные аргументы только для того, чтобы заменять перегрузки

Единственная допустимая причина для использования необязательных аргументов C# 4.0 – это замена примера из правила AV1551 одиночным методом наподобие этого:

public virtual int IndexOf(string phrase, int startIndex = 0, int count = 0) 
{ 
    return someText.IndexOf(phrase, startIndex, count); 
}

Если необязательный параметр является ссылочным типом, то он может иметь в качестве значения по умолчанию только null. Но, как нам известно, string, list и collections никогда не должны быть равны null (согласно правилу AV1135). Поэтому вы должны использовать вместо этого перегруженный метод.

Примечание: Компилятор копирует значение необязательных параметров в место вызова. Поэтому, изменение значения по умолчанию для необязательных параметров должно сопровождаться рекомпиляцией вызывающего кода.
Примечание: Когда метод интерфейса определяет необязательный параметр, его значение по умолчанию не рассматривается во время разрешения перегрузки до тех пор, пока вы не вызовите реализацию этого метода через интерфейс. См. статью Эрика Липперта для получения дополнительной интформации.

AV1555 Избегайте использования именованных аргументов

Именованные аргументы C# 4.0 были созданы для того, чтобы облегчить вызов COM компонентов, которые известны тем, что могут предлагать тонны необязательных параметров. Если вам нужны именованные аргументы, чтобы улучшить читаемость вызова для метода, скорее всего, этот метод делает слишком много и он должен быть подвергнут рефакторингу.

Единственное исключение, где именованные аргументы улучшают читаемость, это ситуация, когда конструктор объекта вызывается, как в примере ниже:

Person person = new Person 
( 
    firstName: "John",  
    lastName: "Smith",  
    dateOfBirth: new DateTime(1970, 1, 1) 
);

AV1561 Не допускайте, чтобы метод или конструктор принимал более трех параметров

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

AV1562 Не используйте ref и out в параметрах

Они делают код менее понятным и создают предпосылки для ошибок. Вместо этого возвращайте составные объекты в качестве результата выполнения функции.

AV1564 Не создавайте методы, которые принимают в качестве параметра логическое значение

Посмотрите на следующий метод:

public Customer CreateCustomer(bool platinumLevel) {}

На первый взгляд все выглядит замечательно, но когда вы будете использовать этот метод, смысл логической переменной полностью потеряет свою ясность:

Customer customer = CreateCustomer(true);

Обычно, если метод принимает булевый флаг в качестве параметра, то он делает более, чем одну вещь и нуждается в рефакторинге для разделения на два или более метода. Альтернативным решением является замена флага перечислением.

AV1568 Не используйте параметры в качестве временных переменных

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

AV1570 Всегда проверяйте результат, возвращаемый оператором as

Если вы используйте оператор as чтобы привести объект к определенному интерфейсу, то всегда проверяйте возвращаемый им результат на null. Невыполнение этого требования может привести к исключению NullReferenceException на гораздо поздней стадии выполнении программы, если объект не реализует требуемый интерфейс.

AV1575 Не оставляйте закомментированные участки кода

Никогда не отправляйте в репозиторий закомментированный код. Вместо этого используйте систему трекинга задач, чтобы следить за тем, какая работа должна быть сделана. Никто впоследствии не догадается, для чего предназначен тот или иной блок закомментированного кода. Он был временно закомментирован для тестирования? Он был скопирован в качестве примера? Должен ли я удалить его?

Элемент языка	Нотация	Пример
Класс, структура	Паскаль	`AppDomain`
Интерфейс	Паскаль	`IBusinessService`
Перечисление (тип)	Паскаль	`ErrorLevel`
Перечисление (значение)	Паскаль	`FatalError`
Событие	Паскаль	`Click`
Приватное поле	Верблюжья нотация	`listItem`
Защищенное поле	Паскаль	`MainPanel`
Константное поле	Паскаль	`MaximumItems`
Константная локальная переменная	Верблюжья нотация	`maximumItems`
Read-only статическое поле	Паскаль	`RedValue`
Переменная	Верблюжья нотация	`listOfValues`
Метод	Паскаль	`ToString`
Пространство имен	Паскаль	`System.Drawing`
Параметр	Верблюжья нотация	`typeName`
Параметры типа	Паскаль	`TView`
Свойство	Паскаль	`BackColor`

Важные ресурсы

Сайт компании

Это документ является частью усилий, направленных на то, чтобы ежедневная работа C# разработчиков шла на профессиональном уровне. Поэтому я размещаю эти рекомендации на сайте CodePlex. Вы легко сможете найти их по ссылке www.csharpcodingguidelines.com.

В дополнение к самой новой версии этого документа вы найдете там:

Список кратких ссылок на данное руководство
Набор правил для Visual Studio 2010/2012 для различных типов систем
Набор правил для ReSharper, которые соответствуют рекомендациям из главы 10
Площадку для обсуждения качества написания кода на C#

Полезные ссылки

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

Code Complete: A Practical Handbook of Software Construction (Steve McConnel). Это одна из лучших книг, которые я когда-либо читал. Она в деталях повествует обо всех аспектах разработки программного обеспечения. Даже несмотря на то, что оригинал этой книги был написан в 2004, вы будете удивлены, когда увидите, насколько актуальны вещи, описанные в ней. Если вы хотите знать серьезность написанных выше слов, я написал ревью на эту книгу в 2009.

The Art of Agile Development (James Shore). Еще одно замечательное всеохватывающее путешествие через многие практики, проповедуемые такими методологиями, как Scrum и экстремальное программирование. Если вы хотите быстро ознакомиться с этими методологиями, обязательно прочитайте книгу Джеймса.

Applying Domain Driven-Design and Patterns: With Examples in C# and .NET (Jimmy Nilsson). Книга, с которой начался мой интерес к предметно-ориентированному проектированию (DDD) и разработке через тестирование (TDD). Это одна из тех книг, которую бы мне следовало прочитать на несколько лет раньше, чтобы избежать многих своих ошибок.

Jeremy D. Miller’s Blog. Несмотря на то, что он больше не ведет этот блог, в последние пару лет им были написаны превосходные статьи о разработке через тестирование, паттернах и принципах проектирования. Я многому научился на его идеях и примерах, взятых из реальной жизни.

LINQ Framework Design Guidelines. Набор правил и рекомендаций, которых вам следует придерживаться при создании своей собственной реализации интерфейса IQueryable.

Best Practices for c# async/await. Источник и обоснование нескольких новых рекомендаций, описанных в этом документе. Автором является Джон Вагнер.

Tags:

Hubs:

Рекомендации по написанию кода на C# от Aviva Solutions

Зачем мне это использовать?

Базовые принципы

Как мне начать?

Почему вы создали это?

Эти рекомендации являются стандартами?

Обратная связь и отказ от ответственности

Рекомендации по проектированию классов

Рекомендации по проектированию членов класса

Различные рекомендации по проектированию

Рекомендации по улучшению сопровождаемости кода

Рекомендации по именованию

Рекомендации по повышению производительности

Рекомендации по использованию фреймворка

Рекомендации по созданию документации

Рекомендации по оформлению

Важные ресурсы

Сайт компании

Полезные ссылки

Articles