Pravidla návrhu

  • Článek

Pravidla návrhu podporují dodržování pokynů pro návrh rozhraní .NET Framework.

V této části

Pravidlo Popis
CA1000: Nedeklarujte statické členy v obecných typech Při volání statického členu obecného typu musí být pro tento typ zadán argument typu. Je-li zavolán obecný člen instance, který nepodporuje odvozování, musí být pro tento člen zadán argument typu. V těchto dvou případech je syntaxe zadávání argumentu typu různá a snadno zaměnitelná.
CA1001: Typy vlastních uvolnitelných polí, které by měly být uvolnitelné Třída deklaruje a implementuje pole instance, které je typem System.IDisposable a třída neimplementuje IDisposable. Třída, která deklaruje pole IDisposable nepřímo, vlastní nespravovaný zdroj a měla by rozhraní IDisposable implementovat.
CA1002: Nezveřejňujte obecné seznamy System.Collections.Generic.List<(Of <(T>)>) je obecná kolekce určená pro výkon, nikoli dědičnost. Proto třída List neobsahuje žádné virtuální členy. Místo ní by měly být vystaveny kolekce navržené pro dědičnost.
CA1003: Použijte instance obecných obslužných rutin události Typ obsahuje delegáta, který vrací identifikátor, jehož podpis obsahuje dva parametry (první objekt a druhý typ, který je možné přiřadit eventArgs) a obsahující cíle sestavení .NET Framework 2.0.
CA1005: Vyhněte se nadbytečným parametrům na obecných typech Čím více parametrů typu obecný typ obsahuje, tím obtížnější je vědět a zapamatovat si, co každý z parametrů typu představuje. Obvykle je to zřejmé pomocí jednoho parametru typu, jako v Seznamu<T>, a v některých případech se dvěma parametry typu, jako v Dictionary<TKey, TValue>. Pokud však existují více než dva parametry typu, stává se pro většinu uživatelů použití příliš obtížným.
CA1008: Výčty by měly mít nulovou hodnotu Výchozí hodnota neinicializovaného výčtu je stejně jako u jiných typů hodnot nula. Atribut nonflags výčtu by měl definovat člen pomocí hodnoty nula, aby výchozí hodnota je platná hodnota výčtu. Definuje-li výčet, který má aplikován atribut FlagsAttribute, člen s hodnotou nula, měl by jeho název být „None“, aby tak označoval, že ve výčtu nebyly nastaveny žádné hodnoty.
CA1010: Kolekce musí implementovat obecné rozhraní Použitelnost kolekce lze rozšířit implementací jednoho z rozhraní obecné kolekce. Pak lze tuto kolekci použít k zaplnění typů obecných kolekcí.
CA1012: Abstraktní typy by neměly mít veřejné konstruktory Konstruktory abstraktních typů mohou být volány pouze odvozenými typy. Jelikož veřejné konstruktory vytvářejí instance typu, přičemž nelze vytvořit instance abstraktního typu, je abstraktní typ obsahující veřejný konstruktor nesprávně navržen.
CA1014: Označte sestavení pomocí atributu CLSCompliantAttribute Specifikace Common Language Specification (CLS) definuje omezení názvů, datové typy a pravidla, která musí sestavení dodržovat, pokud budou použita napříč programovacími jazyky. Dobrý návrh určuje, že všechna sestavení explicitně označují dodržování předpisů CLS pomocí CLSCompliantAttribute. Není-li tento atribut v sestavení přítomen, nedodržuje sestavení specifikaci.
CA1016: Označte sestavení pomocí atributu AssemblyVersionAttribute .NET používá číslo verze k jednoznačné identifikaci sestavení a k vytvoření vazby na typy v sestaveních se silným názvem. Číslo verze je používáno spolu se zásadou verze a vydavatele. Ve výchozím nastavení mohou být aplikace spuštěny pouze ve verzi sestavení, v níž byly sestaveny.
CA1017: Označte sestavení pomocí atributu ComVisibleAttribute Atribut ComVisibleAttribute určuje způsob přístupu klientů COM ke spravovanému kódu. Dobrý návrh přikazuje, aby sestavení explicitně uvedla viditelnost modelu COM. Viditelnost modelu COM může být nastavena pro celé sestavení a poté přepsána pro jednotlivé typy a členy typů. Není-li tento atribut přítomen, je obsah sestavení viditelný klientům COM.
CA1018: Označte atributy pomocí AttributeUsageAttribute Při definování vlastního atributu jej označte použitím atributu AttributeUsageAttribute, čímž je určeno, kde ve zdrojovém kódu může být vlastní atribut použit. Význam a zamýšlené použití atributu určuje jeho platné umístění v kódu.
CA1019: Definujte přístupové objekty pro argumenty atributu Atributy mohou definovat povinné argumenty, které musí být specifikovány při použití atributu na cíl. Říká se jim také poziční argumenty, jelikož jsou konstruktorům atributů předány jako poziční parametry. Pro každý povinný argument by měl atribut navíc poskytovat odpovídající vlastnost jen pro čtení, aby mohla být hodnota argumentu během spuštění získána. Atributy mohou také definovat volitelné argumenty, které jsou rovněž známy jako pojmenované argumenty. Tyto argumenty jsou podle názvu poskytovány konstruktorům atributů a měly by mít odpovídající vlastnost pro čtení i zápis.
CA1021: Vyhněte se výstupním parametrům Předávání typů odkazem (za použití klíčových slov „out“ nebo „ref“) vyžaduje zkušenosti s ukazateli, pochopení, jak se liší typy hodnot a typy odkazů, a schopnost práce s metodami vracejícími více návratových typů. Také rozdíl mezi parametry „out“ a „ref“ není běžně chápán.
CA1024: Použijte vlastnosti, kde je to vhodné Veřejná nebo chráněná metoda má název začínající na „Get“, nepřijímá žádné parametry a vrací hodnotu, která není polem. Metoda může být dobrým kandidátem, aby se stala vlastností.
CA1027: Označte výčty pomocí FlagsAttribute Výčet je typ hodnoty, který definuje množinu souvisejících pojmenovaných konstant. Mohou-li být pojmenované konstanty smysluplně kombinovány, použijte ve výčtu atribut FlagsAttribute.
CA1028: Úložiště výčtu by měl být Int32 Výčet je typ hodnoty, který definuje množinu souvisejících pojmenovaných konstant. Ve výchozím nastavení je pro uložení konstantní hodnoty použit datový typ System.Int32. I když tento základní typ můžete změnit, pro většinu scénářů se nevyžaduje ani nedoporučuje.
CA1030: Použijte události, kde je to vhodné Toto pravidlo zjišťuje metody, které mají názvy obvykle používané pro události. Je-li metoda volána jako odpověď na jednoznačně definovanou změnu stavu, měla by být metoda volána obslužnou rutinou události. Objekty volající tuto metodu by měly místo přímého volání metody vyvolat událost.
CA1031: Nezachycujte výjimky obecného typu Obecné výjimky by neměly být zachycovány. Zachyťte konkrétnější výjimku nebo znovu zvětšte obecnou výjimku jako poslední příkaz v bloku catch.
CA1032: Implementujte standardní konstruktory výjimky Není-li dodána úplná sada konstruktorů, může být obtížné správně ošetřit výjimky.
CA1033: Metody rozhraní by měly být volatelné podřízenými typy Nezapečetěný externě viditelný typ poskytuje explicitní implementaci metod veřejného rozhraní a neposkytuje alternativní externě viditelnou metodu stejného názvu.
CA1034: Vnořené typy by neměly být viditelné Vnořený typ je typ deklarovaný v rámci jiného typu. Vnořené typy jsou užitečné pro zapouzdření soukromých podrobností implementace v daném typu. Jsou-li vnořené typy používány za tímto účelem, neměly by být externě viditelné.
CA1036: Přepište metody srovnatelných typů Veřejný nebo chráněný typ implementuje rozhraní System.IComparable. Nepřepisuje metodu Object.Equals ani nepřetěžuje operátory rovnosti, nerovnosti, menší než a větší než specifické pro daný jazyk.
CA1040: Vyhněte se prázdným rozhraním Rozhraní definují členy ujednávající jejich chování nebo užití. Funkčnost popsaná rozhraním může být osvojena libovolným typem bez ohledu na to, kde se typ vyskytuje v hierarchii dědičnosti. Typ implementuje rozhraní tím, že poskytuje implementace jeho členů. Prázdné rozhraní nedefinuje žádné členy, tudíž ani nedefinuje žádná implementovatelná ujednání.
CA1041: Poskytněte zprávu ObsoleteAttribute Typ nebo člen je označen atributem System.ObsoleteAttribute, aniž by měl zadánu vlastnost ObsoleteAttribute.Message. Pokud je zkompilován typ nebo člen označený pomocí ObsoleteAttribute, zobrazí se vlastnost Message atributu, která uživateli poskytuje informace o zastaralém typu nebo členu.
CA1043: Použijte celočíselný nebo řetězcový argument pro indexery Indexery (tj. indexované vlastnosti) by měly jako index používat celočíselné typy nebo typy řetězců. Tyto typy se obvykle používají pro indexování datových struktur a zvyšují použitelnost knihovny. Použití typu Object by mělo být omezeno na ty případy, kdy během návrhu není možné určit konkrétní celočíselný nebo řetězcový typ.
CA1044: Vlastnosti by neměly být pouze pro zápis Ačkoli je přijatelné a často nezbytné použít vlastnost jen pro čtení, směrnice návrhu zakazují použití vlastností jen pro zápis. Důvodem je skutečnost, že umožnit uživateli nastavit hodnotu a poté uživateli zabránit v zobrazení této hodnoty není bezpečné. Taktéž bez přístupu pro čtení není možné zobrazit stav sdílených objektů, což omezuje jejich užitečnost.
CA1045: Nepředávejte typy odkazem Předávání typů odkazem (za použití klíčových slov „out“ nebo „ref“) vyžaduje zkušenosti s ukazateli, pochopení, jak se liší typy hodnot a typy odkazů, a schopnost práce s metodami vracejícími více návratových typů. Architekti knihoven, kteří navrhují pro širokou cílovou skupinu, by neměli očekávat, že uživatelé budou moct pracovat s parametry out nebo ref.
CA1046: Nepřetěžujte operátory rovnosti na odkazových typech U referenčních typů je výchozí implementace operátoru rovnosti téměř vždy správná. Ve výchozím nastavení jsou dva odkazy rovny, pouze pokud ukazují na stejný objekt.
CA1047: Nedeklarujte chráněné členy v zapečetěných typech Typy deklarují chráněné členy, aby k nim odvozené typy mohly přistupovat nebo je přepisovat. Dle definice nelze dědit zapečetěné typy, což znamená, že nelze volat chráněné metody zapečetěných typů.
CA1050: Deklarujte typy v oborech názvů Typy jsou deklarovány v oborech názvů, aby bylo zabráněno kolizím názvů a zároveň jako způsob organizace souvisejících typů v hierarchii objektů.
CA1051: Nedeklarujte viditelná pole instance Hlavní použití pole by mělo být jako podrobnost implementace. Pole by měla být soukromá nebo vnitřní a měla by být vystavena s použitím vlastností.
CA1052: Statický vlastník typů by měl být zapečetěný Veřejný nebo chráněný typ obsahuje pouze statické členy a není deklarován pomocí zapečetěného modifikátoru (C#) nebo NotInheritable (Visual Basic). Typu, u nějž není zamýšleno dědění, by mělo být prostřednictvím označením zapečetěným modifikátorem zabráněno, aby byl použit jako základní typ.
CA1053: Statický vlastník typů by neměl mít konstruktory Veřejný nebo vnořený veřejný typ deklaruje pouze statické členy a má veřejný nebo chráněný výchozí konstruktor. Konstruktor není nutný, protože volání statických členů nevyžaduje instanci typu. Z důvodu bezpečnosti a zabezpečení by řetězcová přetížení měla volat přetížení identifikátoru URI použitím argumentu řetězce.
CA1054: Parametry identifikátoru URI by neměly být řetězce Pakliže metoda přijímá řetězcovou reprezentaci identifikátoru URI, mělo by být poskytnuto odpovídající přetížení přijímající instanci třídy URI, která tyto služby poskytuje bezpečným a zabezpečeným způsobem.
CA1055: Návratové hodnoty identifikátoru URI by neměly být řetězce Toto pravidlo předpokládá, že metoda vrací identifikátor URI. Řetězcová reprezentace identifikátoru URI je náchylná k chybám analýzy a kódování a může vést k ohrožení bezpečnosti. Třída System.Uri poskytuje tyto služby bezpečným a zabezpečeným způsobem.
CA1056: Vlastnosti identifikátoru URI by neměly být řetězce Toto pravidlo předpokládá, že vlastnost představuje identifikátor URI. Řetězcová reprezentace identifikátoru URI je náchylná k chybám analýzy a kódování a může vést k ohrožení bezpečnosti. Třída System.Uri poskytuje tyto služby bezpečným a zabezpečeným způsobem.
CA1058: Typy by neměly rozšířit určité základní typy Externě viditelný typ rozšiřuje určité základní typy. Použijte jednu z alternativ.
CA1060: Přesuňte volání nespravovaných kódů do třídy NativeMethods Metody volání platformy, například ty, které jsou označené System.Runtime.InteropServices.DllImportAttribute pomocí nebo metod definovaných pomocí klíčového slova Declare v jazyce Visual Basic, přistupují k nespravovanému kódu. Tyto metody by měly patřit třídě NativeMethods, SafeNativeMethods nebo UnsafeNativeMethods.
CA1061: Neskrývejte metody třídy base Metoda základního typu je skryta identicky pojmenovanou metodou v odvozeném typu, kde je předpis parametrů odvozené metody odlišný od odpovídajících typů v předpisu parametrů základní metody pouze ve slaběji odvozených typech.
CA1062: Ověřte argumenty veřejných metod Všechny argumenty odkazu předané externě viditelným metodám by měly být porovnány s hodnotou NULL.
CA1063: Implementuje správně IDisposable Všechny typy IDisposable by měly správně implementovat vzor Dispose.
CA1064: Výjimky by měly být veřejné Interní výjimka je viditelná pouze uvnitř svého vlastního vnitřního rozsahu. Jakmile výjimka přesáhne hranice vnitřního rozsahu, lze pro zachycení výjimky použít pouze základní výjimku. Pokud je vnitřní výjimka zděděna z System.Exception, System.SystemExceptionnebo System.ApplicationException, externí kód nebude mít dostatek informací vědět, co dělat s výjimkou.
CA1065: Nevyvolávejte výjimky v neočekávaných umístěních Metoda, u které není předpokládáno vyvolání výjimky, vyvolá výjimku.
CA1066: Implementace IEquatable při přepsání Equals Typ hodnoty přepíše Equals metodu, ale neimplementuje IEquatable<T>.
CA1067: Přepsání rovná se při implementaci IEquatable Typ implementuje IEquatable<T>, ale nepřepíše Equals metodu.
CA1068: Parametry CancellationToken musí být poslední Metoda má parametr CancellationToken, který není posledním parametrem.
CA1069: Výčty by neměly mít duplicitní hodnoty Výčet obsahuje více členů, kterým je explicitně přiřazena stejná konstantní hodnota.
CA1070: Deklarujte pole událostí jako virtuální Událost podobná poli byla deklarována jako virtuální.