Uppräkningsdesign
Kommentar
Det här innehållet skrivs om med behörighet från Pearson Education, Inc. från Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition. Den utgåvan publicerades 2008, och boken har sedan dess reviderats helt i den tredje utgåvan. En del av informationen på den här sidan kan vara inaktuell.
Uppräkningar är en särskild typ av värdetyp. Det finns två typer av uppräkningar: enkla uppräkningar och flagguppräkningar.
Enkla uppräkningar representerar små stängda uppsättningar med val. Ett vanligt exempel på det enkla uppräkningen är en uppsättning färger.
Flagguppräkningar är utformade för att stödja bitvis åtgärder på uppräkningsvärdena. Ett vanligt exempel på en uppräkning av flaggor är en lista med alternativ.
✔️ Använd en uppräkning för att ange parametrar, egenskaper och returvärden som representerar uppsättningar med värden.
✔️ Gör det bra att använda ett uppräkning i stället för statiska konstanter.
❌ Använd INTE en uppräkning för öppna uppsättningar (till exempel operativsystemversionen, namnen på dina vänner osv.).
❌ Ange INTE reserverade uppräkningsvärden som är avsedda för framtida användning.
Du kan alltid lägga till värden i den befintliga uppräkningen i ett senare skede. Mer information om hur du lägger till värden i uppräkningar finns i Lägga till värden i uppräkningar. Reserverade värden förorenar bara uppsättningen med verkliga värden och tenderar att leda till användarfel.
❌ UNDVIK att offentligt exponera uppräkningar med endast ett värde.
En vanlig metod för att säkerställa framtida utökningsbarhet för C-API:er är att lägga till reserverade parametrar i metodsignaturer. Sådana reserverade parametrar kan uttryckas som uppräkningar med ett enda standardvärde. Detta bör inte göras i hanterade API:er. Med metodöverlagring kan du lägga till parametrar i framtida versioner.
❌ Inkludera INTE sentinel-värden i uppräkningar.
Även om de ibland är användbara för ramverksutvecklare är sentinel-värden förvirrande för användare av ramverket. De används för att spåra uppräkningens tillstånd i stället för att vara ett av värdena från uppsättningen som representeras av uppräkningen.
✔️ Ange värdet noll för enkla uppräkningar.
Överväg att kalla värdet något i stil med "Ingen". Om ett sådant värde inte är lämpligt för just den här uppräkningen bör det vanligaste standardvärdet för uppräkningen tilldelas det underliggande värdet noll.
✔️ ÖVERVÄG att använda Int32 (standardvärdet i de flesta programmeringsspråk) som den underliggande typen av en uppräkning om inget av följande är sant:
Uppräkningen är en uppräkning av flaggor och du har fler än 32 flaggor, eller förväntar dig att ha fler i framtiden.
Den underliggande typen måste skilja sig från Int32 för enklare samverkan med ohanterad kod som förväntar sig olika storleksuppräkningar.
En mindre underliggande typ skulle leda till betydande besparingar i utrymmet. Om du förväntar dig att uppräkningen huvudsakligen ska användas som ett argument för kontrollflödet gör storleken liten skillnad. Storleksbesparingarna kan vara betydande om:
Du förväntar dig att uppräkningen ska användas som ett fält i en mycket ofta instansierad struktur eller klass.
Du förväntar dig att användarna skapar stora matriser eller samlingar av uppräkningsinstanserna.
Du förväntar dig att ett stort antal instanser av uppräkningen ska serialiseras.
För minnesintern användning bör du vara medveten om att hanterade objekt alltid DWORDär justerade, så du behöver i praktiken flera uppräkningar eller andra små strukturer i en instans för att packa en mindre uppräkning med för att göra skillnad, eftersom den totala instansstorleken alltid kommer att avrundas upp till en DWORD.
✔️ DO namn flagga uppräkningar med plural substantiv eller substantiv fraser och enkla uppräkningar med singular substantiv eller substantiv fraser.
❌ UTÖKA System.Enum INTE direkt.
System.Enum är en särskild typ som används av CLR för att skapa användardefinierade uppräkningar. De flesta programmeringsspråk tillhandahåller ett programmeringselement som ger dig åtkomst till den här funktionen. I C# används nyckelordet enum till exempel för att definiera en uppräkning.
Utforma flagguppräkningar
✔️ ANVÄND på System.FlagsAttribute flagguppräkningar. Använd inte det här attributet för enkla uppräkningar.
✔️ Använd två krafter för flagguppräkningsvärdena så att de kan kombineras fritt med hjälp av bitvis ELLER-åtgärden.
✔️ ÖVERVÄG att tillhandahålla särskilda uppräkningsvärden för vanliga kombinationer av flaggor.
Bitvis-åtgärder är ett avancerat begrepp och bör inte krävas för enkla uppgifter. ReadWrite är ett exempel på ett sådant specialvärde.
❌ UNDVIK att skapa flagguppräkningar där vissa kombinationer av värden är ogiltiga.
❌ UNDVIK att använda flagguppräkningsvärden på noll om inte värdet representerar "alla flaggor rensas" och namnges på lämpligt sätt, enligt nästa riktlinje.
✔️ NAMNGE nollvärdet för flagguppräkningar None. För en flagguppräkning måste värdet alltid betyda "alla flaggor rensas".
Lägga till värde i uppräkningar
Det är mycket vanligt att upptäcka att du måste lägga till värden i en uppräkning när du redan har levererat den. Det finns ett potentiellt programkompatibilitetsproblem när det nyligen tillagda värdet returneras från ett befintligt API, eftersom dåligt skrivna program kanske inte hanterar det nya värdet korrekt.
✔️ ÖVERVÄG att lägga till värden i uppräkningar, trots en liten kompatibilitetsrisk.
Om du har verkliga data om programokompatibiliteter som orsakas av tillägg till en uppräkning kan du överväga att lägga till ett nytt API som returnerar de nya och gamla värdena och inaktuella det gamla API:et, som bör fortsätta att returnera bara de gamla värdena. Detta säkerställer att dina befintliga program förblir kompatibla.
Portioner © 2005, 2009 Microsoft Corporation. Med ensamrätt.
Reprinted by permission of Pearson Education, Inc. from Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition by Krzysztof Cwalina and Brad Abrams, publicerad 22 okt 2008 av Addison-Wesley Professional som en del av Microsoft Windows Development Series.