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
varpři deklaraci proměnných s vestavěnými systémovými typy, jako jeint//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
varpř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ů
ass 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
outpří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
defaultpředdefault(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
usingSystem.*ř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í
switchcase//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
publicse 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
ISessionlze pojmenovatTSession.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)