[ELMA3] Стандарты написания программного кода на языке C#

Введение

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

Статический анализатор кода 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 Gonna Need It (или YAGNI). «Вам это не понадобится». Он гласит: «Работайте над решением текущих задач, не пишите код только потому, что думаете, будто он пригодится вам в дальнейшем (вы можете предсказывать будущее?)»;
Don't Repeat Yourself (или DRY). «Не повторяйся». Этот принцип призывает вас воздержаться от дублирования кода в пределах компонента, репозитория или связанного контекста, и при этом не забыть об эвристическом правиле трех;
Четыре принципа объектно-ориентированного программирования: инкапсуляция, абстракция, наследование и полиморфизм;
В общем случае не обязательно, чтобы вся кодовая база строго соответствовала данным рекомендациям. Тем не менее, она должна соответствовать им настолько, насколько это возможно.

Общие рекомендации по проектированию

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

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

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

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

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

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

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

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

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

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

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

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

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

Вызывайте событие с помощью Null-условного оператора. Это предотвратит делегат от изменения конкурирующими потоками.

event EventHandler Notify;

protected virtual void OnNotify(NotifyEventArgs args)  
{
    if (Notify != null) 
    {
        Notify.Invoke(this, args);
    }
}

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

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

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

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

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

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

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

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

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

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

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

class SomeClass  
{}

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

// Правильно  
class MyClass where T : SomeClass  
{
    void SomeMethod(T t)  
    {  
        SomeClass obj = t;  
    }  
}

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

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

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

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

Не используйте `this` и `base` без необходимости (ELMA1251)

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

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

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

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

Создавайте все члены класса `private`, а типы `internal sealed` по умолчанию (ELMA1501)

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

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

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

bool hasOrders = !customer.HasNoOrders;

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

Название сборки должно соответствовать пространству имен, которое она содержит (ELMA1505)

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

EleWise.ELMA.CRM.Web.dll.

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

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

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

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

Примечание: Допускается использование подчеркивания для префиксов, например: Locko_Application.cs, BUD_BudgetTeam.md.

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

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

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

namespace EleWise.ELMA.Model.Entities
{
    // Базовый интерфейс сущности
    public interface IEntity:  : IIdentified
    {
        ...
    }

    // Интерфейс сущности с идентификатором
    public interface IEntity<IdT>:  IEntity
    {
        ...
    }
}

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

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

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

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

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

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

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;

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

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

public class Whatever  
{
    public static readonly Color PapayaWhip = new Color(0xFFEFD5);
    public const int MaxNumberOfWheels = 18;
    public const byte ReadCreateOverwriteMask = 0b0010_1100; 
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

var result = someField = GetSomeMethod();

Исключение: Несколько выражений присваивания в одной строке разрешены при использовании out-переменных, is-паттерна или преобразования в tuple. Например:

bool success = int.TryParse(text, out int result);

if ((items[0] is string text) || (items[1] is Action action))
{
}

(int a, int b) = M();

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

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

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

var countries = new List();
countries.Add("Netherlands");
countries.Add("United States");

var countryLookupTable = new Dictionary<string, string>();
countryLookupTable.Add("NL", "Netherlands");
countryLookupTable.Add("US", "United States");

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

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

var countries = new List { "Netherlands", "United States" };

var countryLookupTable = new Dictionary<string, string>
{
    ["NL"] = "Netherlands",
    ["US"] = "United States"
};

Не производите явного сравнения с `true` или `false` (ELMA1525)

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

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

Сравнение с true или false только допустимо для полей типа bool (Nullable).

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

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

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

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

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

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

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

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

// Лучше сделать так:
if (isActive)
{
    if (isVisible)
    {
        Foo();
    }
    else
    {
        Bar();
    }
}

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

Если блок 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);
        }  
    }  
}

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

Например:

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

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

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

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

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

bool isPositive;

if (value > 0)  
{  
    isPositive = true;  
}  
else  
{  
    isPositive = false;  
}

Делайте так:

bool isPositive = (value > 0);

Вместо:

string classification;

if (value> 0)
{  
    classification = "positive";  
}
else
{
    classification = "negative";
}

return classification;

Пишите:

return (value > 0) ? "positive" : "negative";

Вместо:

int result;

if (offset == null)
{
    result = -1;
}
else
{
    result = offset.Value;
}

return result;

Пишите:

return offset ?? -1;

Примечание

.Net 4.5+

Вместо:

if (employee.Manager != null)
{
    return employee.Manager.Name;
}
else
{
    return null;
}

Пишите:

return employee.Manager?.Name;

Но нужно знать меру, не делайте так:

return workflowTask?.Bookmark?.Instance?.Process?.Header?.Published;

И никогда вот так:

return GetProcessHeader()?.Name;

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

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

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

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

if (NonConstructorMemberUsesNewKeyword(member))
{  
    // что-то делаем
}  


private bool NonConstructorMemberUsesNewKeyword(Member member)  
{  
    return
        (member.HidesBaseClassMember &&
        (member.NodeType != NodeType.InstanceInitializer)  
}

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

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

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

public class MyString  
{
    private string someText;
    
    public int IndexOf(string phrase)
    {  
        return IndexOf(phrase, 0);
    }
    
    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(). Также следует отметить, что параметры с одними и теми же именами должны следовать в одном и том же порядке во всех перегрузках.

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

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

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

public virtual int IndexOf(string phrase, int startIndex = 0, int count = -1)
{
    int length = (count == -1) ? (someText.Length - startIndex) : count;
    return someText.IndexOf(phrase, startIndex, length);
}

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

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

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

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

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

Исключение: Единственным исключением, когда именованые аргументы могут улучшить читаемость, является вызов метода с логическим параметром, исходный код которого вам не доступен. Например:

object[] myAttributes = type.GetCustomAttributes(typeof(MyAttribute), inherit: false);

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

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

Исключение: При использовании инверсии управления и фреймворков инъекции зависимостей часто требуется, чтобы зависимости выставлялись в качестве параметров в конструкторе. До тех пор, пока эти параметры не используются ни для чего другого, кроме как реализации инъекции зависимостей, я бы не стал рассматривать это, как нарушение правила.

Не используйте `ref` и `out` в параметрах (ELMA1562)

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

Исключение: Разрешено объявление и использование методов, которые реализуют TryParse. Например:

bool success = int.TryParse(text, out int number);

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

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

public Customer CreateCustomer(bool platinumLevel) {}

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

Customer customer = CreateCustomer(true);

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

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

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

Отдавайте предпочтение использованию `is` вместо `as` (ELMA1570)

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

Паттерн матчинг помогает предотвратить это и улучшить читаемость. Например, вместо:

var remoteUser = user as RemoteUser;
if (remoteUser != null)
{
}

Пишите:

if (user is RemoteUser remoteUser)
{
}

Внимание!

Данный пример работает только с версии С# 7 Для C# 4 по-прежнему используйте приведение через as с проверкой на null

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

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

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

[ELMA3] Стандарты написания программного кода на языке C#

Введение

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

Класс или интерфейс должны иметь единственное предназначение (ELMA1000)

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

Интерфейс должен быть небольшим и должен быть сфокусирован на решении одной задачи (ELMA1003)

Используйте интерфейс, а не базовый класс, чтобы поддерживать несколько реализаций (ELMA1004)

Используйте интерфейс для реализации слабой связанности между классами (ELMA1005)

Избегайте статических классов (ELMA1008)

Не скрывайте предупреждения компилятора с помощью ключевого слова new (ELMA1010)

Функции, которые используют базовый тип, должны иметь возможность использовать подтипы базового типа, не зная об этом (ELMA1011)

Не ссылайтесь на производные классы из базового класса (ELMA1013)

Объект должен обладать ограниченным знанием о других объектах, которые не имеют непосредственного отношения к этому объекту (ELMA1014)

Избегайте двунаправленной зависимости (ELMA1020)

Классы должны иметь состояние и поведение (ELMA1025)

Классы должны поддерживать свое внутренние состояние непротиворечивым (ELMA1026)

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

Свойства класса должны иметь возможность быть установленными в любом порядке (ELMA1100)

Используйте метод вместо свойства (ELMA1105)

Не используйте взаимоисключающие свойства (ELMA1110)

Метод или свойство должны иметь единственное предназначение (ELMA1115)

Не делайте публичными объекты, описывающие состояние, посредством статических членов (ELMA1125)

Возвращайте IEnumerable<T> или ICollection<T> вместо какой-либо конкретной коллекции (ELMA1130)

Свойства, методы или аргументы, которые представляют из себя строку или коллекцию, никогда не должны быть равны null (ELMA1135)

Определяйте параметры настолько специфичными, насколько это возможно (ELMA1137)

Используйте типы, характерные для вашей предметной области, вместо примитивов (ELMA1140)

Общие рекомендации по проектированию

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

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

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

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

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

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

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

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

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

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

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

Не используйте this и base без необходимости (ELMA1251)

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

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

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

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

Название сборки должно соответствовать пространству имен, которое она содержит (ELMA1505)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Отдавайте предпочтение использованию is вместо as (ELMA1570)

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

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

Используйте американский английский язык (ELMA1701)

Для каждого элемента языка используйте соответствующую нотацию (ELMA1702)

Не включайте числа в наименования переменных, параметров и типов (ELMA1704)

Не используйте префиксы в названиях полей (ELMA1705)

Не используйте аббревиатуры (ELMA1706)

Называйте члены класса, параметры и переменные в соответствии с их назначением, а не типом (ELMA1707):

Именуйте типы, используя словосочетания из существительных или прилагательных (ELMA1708)

При именовании параметров универсальных типов используйте описательные имена (ELMA1709)

Возвращайте `IEnumerable<T>` или `ICollection<T>` вместо какой-либо конкретной коллекции (ELMA1130)

Свойства, методы или аргументы, которые представляют из себя строку или коллекцию, никогда не должны быть равны `null` (ELMA1135)

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

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

Не используйте `this` и `base` без необходимости (ELMA1251)

Создавайте все члены класса `private`, а типы `internal sealed` по умолчанию (ELMA1501)

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

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

Не производите явного сравнения с `true` или `false` (ELMA1525)

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

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

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

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

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

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

Не используйте `ref` и `out` в параметрах (ELMA1562)

Отдавайте предпочтение использованию `is` вместо `as` (ELMA1570)

Используйте `–ing` и `–ed` для событий, которые должны случиться перед и после какого-либо другого события (ELMA1737)

Используйте приставку `On` в названии обработчика события (ELMA1738)

Именуйте группы методов расширений в классе с использованием суффикса `Extensions` (ELMA1745)

Добавляйте суффиксы `Async` или `TaskAsync` к названиям асинхронных методов (ELMA1755)

Используйте `Any()`, чтобы проверить `IEnumerable` на пустоту (ELMA1800)

Используйте `async` только для долговременных и низкоинтенсивных задач (ELMA1820)

Используйте `Task.Run` для высокоинтенсивных задач (ELMA1825)

Избегайте использования `await`/`async` c `Task.Wait` (ELMA1830)

Опасайтесь взаимной блокировки `async`/`await` в однопоточном окружении (ELMA1835)

Используйте псевдонимы типов C# вместо типов из пространства имен `System` (ELMA2201)

Тщательно заполняйте атрибуты в файле `AssemblyInfo.cs` (ELMA2215)

Используйте ключевое слово `dynamic` только при работе с объектами этого типа (ELMA2230)

Старайтесь использовать `async`/`await` вместе с `Task` (ELMA2235)

Документируйте все `public`, `protected` и `internal` типы и члены (ELMA2305)

Будьте осторожны с использованием директивы `#region` (ELMA2407)