Allmänna namngivningskonventioner
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.
I det här avsnittet beskrivs allmänna namngivningskonventioner som rör ordval, riktlinjer för användning av förkortningar och förkortningar samt rekommendationer om hur du undviker att använda språkspecifika namn.
Ordval
✔️ Välj lättläst identifierarnamn.
En egenskap med namnet HorizontalAlignment
är till exempel mer läsbar på engelska än AlignmentHorizontal
.
✔️ Prioritera läsbarhet framför korthet.
Egenskapsnamnet CanScrollHorizontally
är bättre än ScrollableX
(en obskyr referens till X-axeln).
❌ Använd INTE understreck, bindestreck eller andra icke-numeriska tecken.
❌ Använd INTE ungersk notation.
❌ UNDVIK att använda identifierare som är i konflikt med nyckelord för vanliga programmeringsspråk.
Enligt regel 4 i COMMON Language Specification (CLS) måste alla kompatibla språk tillhandahålla en mekanism som ger åtkomst till namngivna objekt som använder ett nyckelord i det språket som identifierare. C# använder till exempel @-tecknet som en escape-mekanism i det här fallet. Det är dock fortfarande en bra idé att undvika vanliga nyckelord eftersom det är mycket svårare att använda en metod med escape-sekvensen än en utan den.
Använda förkortningar och förkortningar
❌ Använd INTE förkortningar eller sammandragningar som en del av identifierarnamnen.
Använd till exempel GetWindow
i stället GetWin
för .
❌ Använd INTE några förkortningar som inte är allmänt accepterade, och även om de är det, endast när det behövs.
Undvika språkspecifika namn
✔️ Använd semantiskt intressanta namn i stället för språkspecifika nyckelord för typnamn.
Är till exempel GetLength
ett bättre namn än GetInt
.
✔️ Använd ett allmänt CLR-typnamn i stället för ett språkspecifikt namn i de sällsynta fall då en identifierare inte har någon semantisk betydelse utöver sin typ.
En metod som konverterar till ska till Int64 exempel ha namnet ToInt64
, inte ToLong
(eftersom Int64 är ett CLR-namn för det C#-specifika aliaset long
). I följande tabell visas flera basdatatyper med clr-typnamnen (samt motsvarande typnamn för C#, Visual Basic och C++).
C# | Visual Basic | C++ | CLR |
---|---|---|---|
sbyte | SByte | Char | SByte |
byte | Byte | osignerat tecken | Byte |
Kort | Kort | Kort | Int16 |
ushort | UInt16 | osignerad kort | UInt16 |
Int | Heltal | Int | Int32 |
Uint | UInt32 | osignerad int | UInt32 |
Lång | Lång | __int64 | Int64 |
ulong | UInt64 | osignerade __int64 | UInt64 |
Flyta | Enda | Flyta | Enda |
Dubbel | Dubbel | Dubbel | Dubbel |
Bool | Boolesk | Bool | Boolesk |
Char | Char | wchar_t | Char |
Sträng | Sträng | Sträng | Sträng |
Objekt | Objekt | Objekt | Objekt |
✔️ Använd ett vanligt namn, till exempel value
eller item
, i stället för att upprepa typnamnet, i de sällsynta fall då en identifierare inte har någon semantisk betydelse och parametertypen inte är viktig.
Namnge nya versioner av befintliga API:er
✔️ Använd ett namn som liknar det gamla API:et när du skapar nya versioner av ett befintligt API.
Detta hjälper till att markera relationen mellan API:erna.
✔️ Föredrar du att lägga till ett suffix i stället för ett prefix för att ange en ny version av ett befintligt API.
Detta hjälper identifiering när du bläddrar i dokumentationen eller använder IntelliSense. Den gamla versionen av API:et ordnas nära de nya API:erna eftersom de flesta webbläsare och IntelliSense visar identifierare i alfabetisk ordning.
✔️ ÖVERVÄG att använda en helt ny, men meningsfull identifierare, i stället för att lägga till ett suffix eller ett prefix.
✔️ Använd ett numeriskt suffix för att ange en ny version av ett befintligt API, särskilt om det befintliga namnet på API:et är det enda namn som är meningsfullt (dvs. om det är en branschstandard) och om det inte är lämpligt att lägga till något meningsfullt suffix (eller ändra namnet).
❌ Använd INTE suffixet "Ex" (eller ett liknande) för en identifierare för att skilja det från en tidigare version av samma API.
✔️ Använd suffixet "64" när du introducerar versioner av API:er som körs på ett 64-bitars heltal (ett långt heltal) i stället för ett 32-bitars heltal. Du behöver bara använda den här metoden när det befintliga 32-bitars-API:et finns. gör det inte för helt nya API:er med endast en 64-bitarsversion.
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.