nopCommerce Dokumentace

Standardy psaní kódu

nopCommerce má specifická pravidla pro psaní kódu, která by vývojáři měli při vytváření zdrojového kódu dodržovat. Soubor .editorconfig ve Visual Studiu pomáhá požadovaný styl kódu vynucovat.

Existují tři podporované kategorie konvencí psaní kódu v .NET:

  • Jazykové konvence
  • Konvence formátování
  • Konvence pojmenování

Jazykové konvence

Nastavení stylu kódu .NET

Kvalifikátory „this.“

Toto pravidlo stylu lze použít na pole, vlastnosti, metody nebo události.

  • Upřednostňujte, aby prvek kódu nebyl uvozen pomocí this.

  • Upřednostňujte, aby pole nebyla uvozena pomocí this.

    //Right
    capacity = 0;
    
    //Wrong
    this.capacity = 0;
    
  • Upřednostňujte, aby vlastnosti nebyly uvozeny pomocí this.

    //Right
    ID = 0;
    
    //Wrong
    this.ID = 0;
    
  • Upřednostňujte, aby metody nebyly uvozeny pomocí this.

    //Right
    Display();
    
    //Wrong
    this.Display();
    
  • Upřednostňujte, aby události nebyly uvozeny pomocí this.

    //Right
    Elapsed += Handler;
    
    //Wrong
    this.Elapsed += Handler;
    

Klíčová slova jazyka místo názvů typů frameworku pro odkazy na typy

Toto pravidlo stylu lze použít na lokální proměnné, parametry metod a členy tříd nebo jako samostatné pravidlo na výrazy přístupu ke členům typu.

  • U typů, které mají své klíčové slovo, upřednostňujte pro lokální proměnné, parametry metod a členy tříd klíčové slovo jazyka namísto názvu typu.

    //Right
    private int _member;
    
    //Wrong
    private Int32 _member;
    
  • U typů, které mají své klíčové slovo, upřednostňujte ve výrazech přístupu ke členům klíčové slovo jazyka namísto názvu typu.

    //Right
    var local = int.MaxValue;
    
    //Wrong
    var local = Int32.MaxValue;
    

Předvolby modifikátorů

Pravidla stylu v této části se týkají předvoleb modifikátorů, včetně vyžadování modifikátorů přístupnosti, určení požadovaného pořadí modifikátorů a vyžadování modifikátoru jen pro čtení.

  • Upřednostňujte deklarování modifikátorů přístupnosti s výjimkou veřejných členů rozhraní.

    //Right
    class MyClass
    {
        private const string thisFieldIsConst = "constant";
    }
    
    //Wrong
    class MyClass
    {
        const string thisFieldIsConst = "constant";
    }
    
  • Upřednostňujte uvedené pořadí:

    public, private, protected, internal, static, extern, new, virtual, abstract, sealed, override, readonly, unsafe, volatile, async:silent

    //Right
    class MyClass
    {
        private static readonly int _daysInYear = 365;
    }
    

Předvolby závorek

Pravidla stylu v této části se týkají předvoleb závorek, včetně používání závorek u aritmetických, relačních a dalších binárních operátorů.

  • Upřednostňujte závorky pro vyjasnění priority aritmetických operátorů (*, /, %, +, -, <<, >>, &, ^, |)

    //Right
    var v = a + (b * c);
    
    //Wrong
    var v = a + b * c;
    
  • Upřednostňujte závorky pro vyjasnění priority relačních operátorů (>, <, <=, >=, is, as, ==, !=)

    //Right
    var v = (a < b) == (c > d);
    
    //Wrong
    var v = a < b == c > d;
    
  • Upřednostňujte závorky pro vyjasnění priority ostatních binárních operátorů (&&, ||, ??)

    //Right
    var v = a || (b && c);
    
    //Wrong
    var v = a || b && c;
    
  • Upřednostňujte vynechání závorek, pokud je priorita operátorů zřejmá

    //Right
    var v = a.b.Length;
    
    //Wrong
    var v = (a.b).Length;
    

Předvolby na úrovni výrazů

Pravidla stylu v této části se týkají předvoleb na úrovni výrazů, včetně používání inicializátorů objektů, inicializátorů kolekcí, explicitních nebo odvozených názvů prvků n-tic a odvozených anonymních typů.

  • Upřednostňujte inicializaci objektů pomocí inicializátorů objektů, pokud je to možné

    //Right
    var c = new Customer() { Age = 21 };
    
    //Wrong
    var c = new Customer();
    c.Age = 21;
    
  • Upřednostňujte inicializaci kolekcí pomocí inicializátorů kolekcí, pokud je to možné

    //Right
    var list = new List<int> { 1, 2, 3 };
    
    //Wrong
    var list = new List<int>();
    list.Add(1);
    list.Add(2);
    list.Add(3);
    
  • Upřednostňujte názvy prvků n-tic před vlastnostmi ItemX

    //Right
    (string name, int age) customer = GetCustomer();
    var name = customer.name;
    
    //Wrong
    (string name, int age) customer = GetCustomer();
    var name = customer.Item1;
    
  • Upřednostňujte odvozené názvy prvků n-tic

    //Right
    var tuple = (age, name);
    
    //Wrong
    var tuple = (age: age, name: name);
    
  • Upřednostňujte explicitní názvy členů anonymních typů

    //Right
    var anon = new { age = age, name = name };
    
    //Wrong
    var anon = new { age, name };
    
  • Upřednostňujte automatické vlastnosti před vlastnostmi s privátními podkladovými poli

    //Right
    private int Age { get; }
    
    //Wrong
    private int age;
    
    public int Age
    {
        get
        {
            return age;
        }
    }
    
  • Upřednostňujte kontrolu null pomocí porovnávání vzorů (pattern matching) před object.ReferenceEquals

    //Right
    if (value is null)
        return;
    
    //Wrong
    if (object.ReferenceEquals(value, null))
        return;
    
  • Upřednostňujte přiřazení s ternárním podmíněným operátorem před příkazem if-else

    //Right
    string s = expr ? "hello" : "world";
    
    //Wrong
    string s;
    if (expr)
    {
        s = "hello";
    }
    else
    {
        s = "world";
    }
    
  • Upřednostňujte v příkazech return ternární podmíněný operátor před příkazem if-else

    //Right
    return expr ? "hello" : "world";
    
    //Wrong
    if (expr)
    {
        return "hello";
    }
    else
    {
        return "world";
    }
    
  • Upřednostňujte složené výrazy přiřazení

    //Right
    x += 1;
    
    //Wrong
    x = x + 1;
    

Předvolby kontroly null

Pravidla stylu v této části se týkají předvoleb kontroly null.

  • Upřednostňujte výrazy s operátorem nulového sjednocení (null coalescing) před kontrolou ternárním operátorem

    //Right
    var v = x ?? y;
    
    //Wrong
    var v = x != null ? x : y; // or
    var v = x == null ? y : x;
    
  • Upřednostňujte používání podmíněného operátoru null (null-conditional), pokud je to možné

    //Right
    var v = o?.ToString();
    
    //Wrong
    var v = o == null ? null : o.ToString(); // or
    var v = o != null ? o.String() : null;
    

Nastavení stylu kódu C#

Implicitní a explicitní typy

Pravidla stylu v této části se týkají používání klíčového slova var oproti explicitnímu typu v deklaraci proměnné. Toto pravidlo lze uplatnit samostatně na vestavěné typy, na případy, kdy je typ zřejmý, a jinde.

  • Upřednostňujte var při deklaraci proměnných s vestavěnými systémovými typy, jako je int

    //Right
    var x = 5;
    
    //Wrong
    int x = 5;
    
  • Upřednostňujte var, pokud je typ již uveden na pravé straně deklaračního výrazu

    //Right
    var obj = new Customer();
    
    //Wrong
    Customer obj = new Customer();
    
  • Upřednostňujte var před explicitním typem ve všech případech, pokud to nepřepíše jiné pravidlo stylu kódu

    //Right
    var f = this.Init();
    
    //Wrong
    bool f = this.Init();
    

Členy s tělem ve formě výrazu

Pravidla stylu v této části se týkají používání členů s tělem ve formě výrazu, pokud se logika skládá z jediného výrazu. Toto pravidlo lze použít na metody, konstruktory, operátory, vlastnosti, indexery a přístupové metody.

  • Upřednostňujte bloková těla u metod

    //Right
    public int GetAge() { return this.Age; }
    
    //Wrong
    public int GetAge() => this.Age;
    
  • Upřednostňujte bloková těla u konstruktorů

    //Right
    public Customer(int age) { Age = age; }
    
    //Wrong
    public Customer(int age) => Age = age;
    
  • Upřednostňujte bloková těla u operátorů

    //Right
    public static ComplexNumber operator + (ComplexNumber c1, ComplexNumber c2)
    { return new ComplexNumber(c1.Real + c2.Real, c1.Imaginary + c2.Imaginary); }
    
    //Wrong
    public static ComplexNumber operator + (ComplexNumber c1, ComplexNumber c2)
        => new ComplexNumber(c1.Real + c2.Real, c1.Imaginary + c2.Imaginary);
    
  • Upřednostňujte těla ve formě výrazu u vlastností, pokud se vejdou na jeden řádek

    //Right
    public int Age => _age;
    
    //Wrong
    public int Age { get { return _age; }}
    
  • Upřednostňujte těla ve formě výrazu u indexerů

    //Right
    public T this[int i] => _values[i];
    
    //Wrong
    public T this[int i] { get { return _values[i]; } }
    
  • Upřednostňujte těla ve formě výrazu u přístupových metod

    //Right
    public int Age { get => _age; set => _age = value; }
    
    //Wrong
    public int Age { get { return _age; } set { _age = value; } }
    
  • Upřednostňujte těla ve formě výrazu u lambda výrazů

    //Right
    Func<int, int> square = x => x * x;
    
    //Wrong
    Func<int, int> square = x => { return x * x; };
    

Porovnávání vzorů

Pravidla stylu v této části se týkají používání porovnávání vzorů (pattern matching) v C#.

  • Upřednostňujte porovnávání vzorů namísto výrazů is s přetypováním

    //Right
    if (o is int i) {...}
    
    //Wrong
    if (o is int) {var i = (int)o; ... }
    
  • Upřednostňujte porovnávání vzorů namísto výrazů as s kontrolou null pro zjištění, zda je něco určitého typu

    //Right
    if (o is string s) {...}
    
    //Wrong
    var s = o as string;
    if (s != null) {...}
    

Vložené deklarace proměnných

Toto pravidlo stylu se týká toho, zda jsou proměnné out deklarovány přímo na místě (inline), nebo ne. Od C# 7 můžete deklarovat proměnnou out v seznamu argumentů volání metody namísto samostatné deklarace proměnné.

  • Upřednostňujte deklaraci proměnných out přímo v seznamu argumentů volání metody, pokud je to možné

    //Right
    if (int.TryParse(value, out int i)) {...}
    
    //Wrong
    int i;
    if (int.TryParse(value, out i)) {...}
    

Předvolby C# na úrovni výrazů

Toto pravidlo stylu se týká používání literálu default pro výrazy výchozí hodnoty, pokud kompilátor dokáže typ výrazu odvodit.

  • Upřednostňujte default před default(T)

    //Right
    void DoWork(CancellationToken cancellationToken = default) { ... }
    
    //Wrong
    void DoWork(CancellationToken cancellationToken = default(CancellationToken)) {   ... }
    

Předvolby C# pro kontrolu null

Tato pravidla stylu se týkají syntaxe kolem kontroly null, včetně používání výrazů throw nebo příkazů throw a toho, zda při volání lambda výrazu provést kontrolu null, nebo použít podmíněný operátor (?.).

  • Upřednostňujte výrazy throw namísto příkazů throw

    //Right
    this.s = s ?? throw new ArgumentNullException(nameof(s));
    
    //Wrong
    if (s == null) { throw new ArgumentNullException(nameof(s)); }
    this.s = s;
    
  • Při volání lambda výrazu upřednostňujte podmíněný operátor (?.) namísto provádění kontroly null

    //Right
    func?.Invoke(args);
    
    //Wrong
    if (func != null) { func(args); }
    

Předvolby bloků kódu

Toto pravidlo stylu se týká používání složených závorek k ohraničení bloků kódu.

  • Upřednostňujte vynechání složených závorek, pokud je to povoleno

    //Right
    if (test) this.Display();
    
    //Wrong
    if (test) { this.Display(); }
    

Konvence formátování

Nastavení formátování .NET

Uspořádání direktiv using

Tato pravidla formátování se týkají řazení a zobrazení direktiv using a příkazů Imports.

  • Direktivy using System.* řaďte abecedně a umisťujte je před ostatní direktivy using.

    //Right
    using System.Collections.Generic;
    using System.Threading.Tasks;
    using Octokit;
    
    //Wrong
    using System.Collections.Generic;
    using Octokit;
    using System.Threading.Tasks;
    
  • Mezi skupiny direktiv using nevkládejte prázdný řádek.

    //Right
    using System.Collections.Generic;
    using System.Threading.Tasks;
    using Octokit;
    
    //Wrong
    using System.Collections.Generic;
    using System.Threading.Tasks;
    
    using Octokit;
    

Nastavení formátování C#

Pravidla formátování v této části platí pouze pro kód C#.

Možnosti nových řádků

Tato pravidla formátování se týkají používání nových řádků k formátování kódu.

  • Vyžadujte, aby složené závorky byly u všech výrazů na novém řádku (styl „Allman“).

    //Right
    void MyMethod()
    {
        if (...)
        {
            ...
        }
    }
    
    //Wrong
    void MyMethod() {
        if (...) {
            ...
        }
    }
    
  • Příkazy else umisťujte na nový řádek.

    //Right
    if (...) 
    {
        ...
    }
    else 
    {
        ...
    }
    
    //Wrong
    if (...) {
        ...
    } else {
        ...
    }
    
  • Příkazy catch umisťujte na nový řádek.

    //Right
    try 
    {
        ...
    }
    catch (Exception e) 
    {
        ...
    }
    
    //Wrong
    try {
        ...
    } catch (Exception e) {
        ...
    }
    
  • Vyžadujte, aby příkazy finally byly na novém řádku za uzavírací složenou závorkou.

    //Right
    try 
    {
        ...
    }
    catch (Exception e) 
    {
        ...
    }
    finally 
    {
        ...
    }
    
    //Wrong
    try {
        ...
    } catch (Exception e) {
        ...
    } finally {
        ...
    }
    
  • Vyžadujte, aby členy inicializátorů objektů byly na samostatných řádcích

    //Right
    var z = new B()
    {
        A = 3,
        B = 4
    }
    
    //Wrong
    var z = new B()
    {
        A = 3, B = 4
    }
    
  • Vyžadujte, aby členy anonymních typů byly na samostatných řádcích

    //Right
    var z = new
    {
        A = 3,
        B = 4
    }
    
    //Wrong
    var z = new
    {
        A = 3, B = 4
    }
    
  • Vyžadujte, aby prvky klauzulí dotazových výrazů byly na samostatných řádcích

    //Right
    var q = from a in e
            from b in e
            select a * b;
    
    //Wrong
    var q = from a in e from b in e
            select a * b;
    

Možnosti odsazení

Tato pravidla formátování se týkají používání odsazení k formátování kódu.

  • Odsazujte obsah větví switch case

    //Right
    switch(c) 
    {
        case Color.Red:
            Console.WriteLine("The color is red");
            break;
        case Color.Blue:
            Console.WriteLine("The color is blue");
            break;
        default:
            Console.WriteLine("The color is unknown.");
            break;
    }
    
    //Wrong
    switch(c) {
        case Color.Red:
        Console.WriteLine("The color is red");
        break;
        case Color.Blue:
        Console.WriteLine("The color is blue");
        break;
        default:
        Console.WriteLine("The color is unknown.");
        break;
    }
    
  • Odsazujte návěští switch

    //Right
    switch(c) 
    {
        case Color.Red:
            Console.WriteLine("The color is red");
            break;
        case Color.Blue:
            Console.WriteLine("The color is blue");
            break;
        default:
            Console.WriteLine("The color is unknown.");
            break;
    }
    
    //Wrong
    switch(c) {
    case Color.Red:
        Console.WriteLine("The color is red");
        break;
    case Color.Blue:
        Console.WriteLine("The color is blue");
        break;
    default:
        Console.WriteLine("The color is unknown.");
        break;
    }
    
  • Návěští se umisťují na stejné odsazení jako aktuální kontext

    //Right
    class C
    {
        private string MyMethod(...)
        {          
            if (...) 
            {
                goto error;
            }
            error:
            throw new Exception(...);
        }
    }
    
    //Wrong
    class C
    {
        private string MyMethod(...)
        {
            if (...) {
                goto error;
            }
    error:
            throw new Exception(...);
        }
    }
    
    //Wrong
    class C
    {
        private string MyMethod(...)
        {
            if (...) {
                goto error;
            }
        error:
            throw new Exception(...);
        }
    }
    

Možnosti mezer

Tato pravidla formátování se týkají používání mezer k formátování kódu.

  • Odstraňte mezeru mezi přetypováním a hodnotou

    //Right
    int y = (int)x;
    
    //Wrong
    int y = (int) x;
    
  • Za klíčové slovo v příkazu řízení toku, jako je cyklus for, vložte mezeru

    //Right
    for (int i;i<x;i++) { ... }
    
    //Wrong
    for(int i;i<x;i++) { ... }
    
  • Před dvojtečku pro základní třídy nebo rozhraní v deklaraci typu vložte mezeru

    //Right
    interface I
    {
    
    }
    
    class C : I
    {
    
    }
    
    //Wrong
    interface I
    {
    
    }
    
    class C: I
    {
    
    }
    
  • Za dvojtečku pro základní třídy nebo rozhraní v deklaraci typu vložte mezeru

    //Right
    interface I
    {
    
    }
    
    class C : I
    {
    
    }
    
    //Wrong
    interface I
    {
    
    }
    
    class C :I
    {
    
    }
    
  • Vložte mezeru před binární operátor a za něj

    //Right
    return x * (x - y);
    
    //Wrong
    return x*(x-y);
    
    //Wrong
    return x  *  (x-y);
    
  • Odstraňte mezery za otevírací závorkou a před uzavírací závorkou seznamu parametrů v deklaraci metody

    //Right
    void Bark(int x) { ... }
    
    //Wrong
    void Bark( int x ) { ... }
    
  • Odstraňte mezeru v prázdných závorkách seznamu parametrů v deklaraci metody

    //Right
    void Goo()
    {
        Goo(1);
    }
    
    void Goo(int x)
    {
        Goo();
    }
    
    //Wrong
    void Goo( )
    {
        Goo(1);
    }
    
    void Goo(int x)
    {
        Goo();
    }
    
    
  • Odstraňte mezery mezi názvem metody a otevírací závorkou v deklaraci metody

    //Right
    void M() { }
    
    //Wrong
    void M () { }
    
  • Odstraňte mezery za otevírací závorkou a před uzavírací závorkou při volání metody

    //Right
    MyMethod(argument);
    
    //Wrong
    MyMethod( argument );
    
  • Odstraňte mezeru v prázdných závorkách seznamu argumentů

    //Right
    void Goo()
    {
        Goo(1);
    }
    
    void Goo(int x)
    {
        Goo();
    }
    
    //Wrong
    void Goo()
    {
        Goo(1);
    }
    
    void Goo(int x)
    {
        Goo( );
    }
    
  • Odstraňte mezeru mezi názvem volané metody a otevírací závorkou

    //Right
    void Goo()
    {
        Goo(1);
    }
    
    void Goo(int x)
    {
        Goo();
    }
    
    //Wrong
    void Goo()
    {
        Goo(1);
    }
    
    void Goo(int x)
    {
        Goo ();
    }
    
  • Za čárku vložte mezeru

    //Right
    int[] x = new int[] { 1, 2, 3, 4, 5 };
    
    //Wrong
    int[] x = new int[] { 1,2,3,4,5 };
    
  • Odstraňte mezeru před čárkou

    //Right
    int[] x = new int[] { 1, 2, 3, 4, 5 };
    
    //Wrong
    int[] x = new int[] { 1 , 2 , 3 , 4 , 5 };
    
  • V příkazu for vložte mezeru za každý středník

    //Right
    for (int i = 0; i < x.Length; i++)
    
    //Wrong
    for (int i = 0;i < x.Length;i++)
    
  • V příkazu for odstraňte mezeru před každým středníkem

    //Right
    for (int i = 0; i < x.Length; i++)
    
    //Wrong
    for (int i = 0 ; i < x.Length ; i++)
    
  • Odstraňte nadbytečné mezery v deklaračních příkazech

    //Right
    int x = 0;
    
    //Wrong
    int    x    =    0   ;
    
  • Odstraňte mezeru před otevírací hranatou závorkou [

    //Right
    int[] numbers = new int[] { 1, 2, 3, 4, 5 };
    
    //Wrong
    int [] numbers = new int [] { 1, 2, 3, 4, 5 };
    
  • Odstraňte mezeru mezi prázdnými hranatými závorkami []

    //Right
    int[] numbers = new int[] { 1, 2, 3, 4, 5 };
    
    //Wrong
    int[ ] numbers = new int[ ] { 1, 2, 3, 4, 5 };
    
  • Odstraňte mezery v neprázdných hranatých závorkách [0]

    //Right
    int index = numbers[0];
    
    //Wrong
    int index = numbers[ 0 ];
    

Možnosti zalomení

Tato pravidla formátování se týkají umístění příkazů a bloků kódu na jeden řádek oproti samostatným řádkům.

  • Ponechte příkazy a deklarace členů na různých řádcích

    //Right
    int i = 0;
    string name = "John";
    
    //Wrong
    int i = 0; string name = "John";
    
  • Ponechte blok kódu na jednom řádku

    //Right
    public int Foo { get; set; }
    
    //Wrong
    public int MyProperty
    {
        get; set;
    }
    

Konvence pojmenování

  • Konstanty se pojmenovávají pouze velkými písmeny s oddělovačem _

    //Right
    const int TEST_CONSTANT = 1;
    
    //Wrong
    const int Test_Constant = 1;
    
  • Pole s přístupem public se pojmenovávají v notaci PascalCase

    //Right
    public int TestField;
    
    //Wrong
    public int testField;
    
  • Názvy rozhraní musí být v notaci PascalCase a mít předponu I

    //Right
    public interface ITestInterface;
    
    //Wrong
    public interface testInterface;
    
  • Názvy tříd, struktur, metod, výčtů, událostí, vlastností, jmenných prostorů a delegátů by měly být v notaci PascalCase

    //Right
    public class SomeClass;
    
    //Wrong
    public class someClass;
    
  • Pro parametr generického typu používejte popisný název v notaci PascalCase, pokud nestačí jedno písmeno a popisný název nepřináší žádnou přidanou hodnotu.

    //Right
    public interface ISessionChannel<TSession> { /*...*/ }
    public delegate TOutput Converter<TInput, TOutput>(TInput from);
    public class List<T> { /*...*/ }
    
  • Pro typy, které obsahují pouze jednopísmenný typový parametr, použijte jako název typového parametru T

    //Right
    public int IComparer<T>() { return 0; }
    public delegate bool Predicate<T>(T item);
    public struct Nullable<T> where T : struct { /*...*/ }
    
  • Pro popisné názvy typových parametrů používejte předponu T

    //Right
    public interface ISessionChannel<TSession>
    {
        TSession Session { get; }
    }
    

    Omezení spojená s typovým parametrem uveďte v jeho názvu. Například parametr s omezením ISession lze pojmenovat TSession.

  • Privátní a chráněná pole tříd musí začínat předponou _

    //Right
    private int _testField;
    protected int _testField;
    
    //Wrong
    private int testField;
    protected int testField;
    
  • Všechny ostatní prvky kódu, jako jsou proměnné, parametry metod a pole tříd (kromě veřejných), se pojmenovávají v notaci camelCase.

    //Right
    var testVar = new Object();
    public void Foo(int firstParam, string secondParam)
    
    //Wrong
    var TestVar = new Object();
    public void Foo(int FirstParam, string SecondParam)
    
Přispěvatelé: AndreiMaz DmitriyKulagin
Upravit na GitHubu