Algemene naamconventies
Notitie
Deze inhoud wordt opnieuw afgedrukt door toestemming van Pearson Education, Inc. van Framework Design Guidelines: Conventions, Idioms en Patterns for Reusable .NET Libraries, 2nd Edition. Die editie werd in 2008 gepubliceerd en het boek is sindsdien volledig herzien in de derde editie. Sommige informatie op deze pagina is mogelijk verouderd.
In deze sectie worden algemene naamconventies beschreven die betrekking hebben op woordkeuze, richtlijnen voor het gebruik van afkortingen en acroniemen en aanbevelingen voor het vermijden van taalspecifieke namen.
Woordkeuze
✔️ KIES gemakkelijk leesbare id-namen.
Een eigenschap met de naam HorizontalAlignment is bijvoorbeeld beter leesbaar in het Engels dan AlignmentHorizontal.
✔️ DOE de voorkeursleesbaarheid ten opzichte van de beknoptheid.
De naam CanScrollHorizontally van de eigenschap is beter dan ScrollableX (een verborgen verwijzing naar de X-as).
❌ GEBRUIK GEEN onderstrepingstekens, afbreekstreepjes of andere niet-phanumerische tekens.
❌ Gebruik geen Hongaarse notatie.
❌ VERMIJD het gebruik van id's die conflicteren met trefwoorden van veelgebruikte programmeertalen.
Volgens regel 4 van de Common Language Specification (CLS) moeten alle compatibele talen een mechanisme bieden waarmee toegang wordt geboden tot benoemde items die een trefwoord van die taal als id gebruiken. C# gebruikt bijvoorbeeld het @-teken als een escape-mechanisme in dit geval. Het is echter nog steeds een goed idee om veelvoorkomende trefwoorden te vermijden, omdat het veel moeilijker is om een methode te gebruiken met de escape-reeks dan één zonder deze.
Afkortingen en acroniemen gebruiken
❌ GEBRUIK GEEN afkortingen of samentrekkingen als onderdeel van id-namen.
Gebruik bijvoorbeeld in plaats GetWinvan GetWindow .
❌ GEBRUIK GEEN acroniemen die niet algemeen worden geaccepteerd, en zelfs niet als dat nodig is.
Taalspecifieke namen vermijden
✔️ GEBRUIK semantisch interessante namen in plaats van taalspecifieke trefwoorden voor typenamen.
Is bijvoorbeeld GetLength een betere naam dan GetInt.
✔️ GEBRUIK een algemene CLR-typenaam, in plaats van een taalspecifieke naam, in de zeldzame gevallen wanneer een id geen semantische betekenis heeft buiten het type.
Een methode die moet Int64 worden geconverteerd, moet bijvoorbeeld een naam ToInt64hebben, niet ToLong (omdat Int64 dit een CLR-naam is voor de C#-specifieke alias long). De volgende tabel bevat verschillende basisgegevenstypen met behulp van de CLR-typenamen (evenals de bijbehorende typenamen voor C#, Visual Basic en C++).
| C# | Visual Basic | C++ | CLR |
|---|---|---|---|
| sbyte | SByte | Char | SByte |
| Byte | Byte | teken zonder teken | Byte |
| Korte | Korte | Korte | Int16 |
| ushort | UInt16 | niet-ondertekende korte | UInt16 |
| int | Geheel getal | int | Int32 |
| Uint | UInt32 | niet-ondertekende int | UInt32 |
| Lange | Lange | __int64 | Int64 |
| ulong | UInt64 | niet-ondertekende __int64 | UInt64 |
| Float | Één | Float | Één |
| Dubbele | Dubbel | Dubbele | Dubbel |
| bool | Booleaanse waarde | bool | Booleaanse waarde |
| Char | Char | wchar_t | Char |
| Tekenreeks | Tekenreeks | Tekenreeks | Tekenreeks |
| Object | Object | Object | Object |
✔️ Gebruik een algemene naam, zoals value of item, in plaats van de typenaam te herhalen, in zeldzame gevallen wanneer een id geen semantische betekenis heeft en het type van de parameter niet belangrijk is.
Nieuwe versies van bestaande API's een naam geven
✔️ Gebruik een naam die vergelijkbaar is met de oude API bij het maken van nieuwe versies van een bestaande API.
Dit helpt bij het markeren van de relatie tussen de API's.
✔️ Voeg liever een achtervoegsel toe in plaats van een voorvoegsel om een nieuwe versie van een bestaande API aan te geven.
Dit helpt bij het zoeken naar documentatie of bij het gebruik van IntelliSense. De oude versie van de API wordt dicht bij de nieuwe API's ingedeeld, omdat in de meeste browsers en IntelliSense id's in alfabetische volgorde worden weergegeven.
✔️ OVERWEEG een gloednieuwe, maar zinvolle id te gebruiken in plaats van een achtervoegsel of voorvoegsel toe te voegen.
✔️ Gebruik een numeriek achtervoegsel om een nieuwe versie van een bestaande API aan te geven, met name als de bestaande naam van de API de enige naam is die zinvol is (bijvoorbeeld als het een industriestandaard is) en als het toevoegen van een zinvol achtervoegsel (of het wijzigen van de naam) geen geschikte optie is.
❌ GEBRUIK HET achtervoegsel Ex (of een vergelijkbaar) voor een id NIET om deze te onderscheiden van een eerdere versie van dezelfde API.
✔️ Gebruik het achtervoegsel '64' bij het introduceren van versies van API's die werken op een 64-bits geheel getal (een lang geheel getal) in plaats van een 32-bits geheel getal. U hoeft deze benadering alleen te gebruiken wanneer de bestaande 32-bits API bestaat; doe dit niet voor gloednieuwe API's met slechts een 64-bits versie.
© Delen 2005, 2009 Microsoft Corporation. Alle rechten voorbehouden.
Herdrukt door toestemming van Pearson Education, Inc. van Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition by Krzysztof Cwalina and Brad Abrams, published oct 22, 2008 by Addison-Wesley Professional als onderdeel van de Microsoft Windows Development Series.