Általános elnevezési egyezmények
Feljegyzés
Ezt a tartalmat a Pearson Education, Inc. engedélyével nyomtatjuk újra a Framework Design Guidelines: Conventions, Idioms és Patterns for Reusable .NET Libraries, 2nd Edition engedélyével. Ezt a kiadást 2008-ban adták ki, és a könyvet azóta teljesen átdolgozták a harmadik kiadásban. Előfordulhat, hogy az oldalon található információk némelyike elavult.
Ez a szakasz a szóválasztással kapcsolatos általános elnevezési konvenciókról, a rövidítések és betűszók használatának irányelveiről, valamint a nyelvspecifikus nevek használatának elkerülésére vonatkozó javaslatokat ismerteti.
A Word választási lehetősége
✔️ A DO könnyen olvasható azonosítóneveket választhat.
Egy elnevezett HorizontalAlignment
tulajdonság például angolul olvashatóbb, mint AlignmentHorizontal
a .
✔️ DO az olvashatóság előnyben részesítve a rövidséget.
A tulajdonság neve CanScrollHorizontally
jobb, mint ScrollableX
(az X tengelyre mutató homályos hivatkozás).
❌ NE használjon aláhúzásjeleket, kötőjeleket vagy bármely más nonalphanumerikus karaktert.
❌ NE használjon magyar jelölést.
❌ KERÜLJE olyan azonosítók használatát, amelyek ütköznek a széles körben használt programozási nyelvek kulcsszavaival.
A Common Language Specification (CLS) 4. szabálya szerint minden megfelelő nyelvnek olyan mechanizmust kell biztosítania, amely lehetővé teszi az adott nyelv kulcsszóját azonosítóként használó elnevezett elemek elérését. A C#például a @ jelet használja menekülési mechanizmusként ebben az esetben. Azonban még mindig jó ötlet elkerülni a gyakori kulcsszavakat, mert sokkal nehezebb használni egy metódust a menekülési sorozat, mint egy nélküle.
Rövidítések és mozaikszavak használata
❌ NE használjon rövidítéseket vagy összevonásokat az azonosítónevek részeként.
Például használja GetWindow
ahelyett, hogy GetWin
.
❌ NE használjon olyan rövidítéseket, amelyek széles körben nem elfogadottak, és még akkor is, ha igen, csak akkor, ha szükséges.
Nyelvspecifikus nevek elkerülése
✔️ A DO nyelvspecifikus kulcsszavak helyett szemantikailag érdekes neveket használjon a típusnevekhez.
Például jobb név, GetLength
mint GetInt
.
✔️ A DO nyelvspecifikus név helyett általános CLR-típusnevet használ azokban a ritka esetekben, amikor egy azonosítónak nincs a típusán túli szemantikai jelentése.
Egy metódust például el kell nevezni Int64ToInt64
, nem ToLong
(mert Int64 a C#-specifikus alias long
CLR-neve). Az alábbi táblázat számos alapadattípust mutat be a CLR-típusnevek használatával (valamint a C#, a Visual Basic és a C++ megfelelő típusneveit).
C# | Visual Basic | C++ | CLR |
---|---|---|---|
sbyte | SByte | Char | SByte |
bájt | Bájt | aláíratlan karakter | Bájt |
Rövid | Rövid | Rövid | Int16 |
ushort | UInt16 | aláíratlan rövid | UInt16 |
Int | Egész | Int | Int32 |
uint | UInt32 | aláíratlan int | UInt32 |
Hosszú | Hosszú | __int64 | Int64 |
ulong | UInt64 | aláíratlan __int64 | UInt64 |
Úszó | Egyetlen | Úszó | Egyetlen |
Dupla | Dupla | Dupla | Dupla |
Bool | Logikai | Bool | Logikai |
Char | Char | wchar_t | Char |
húr | Sztring | Sztring | Sztring |
Objektum | Objektum | Objektum | Objektum |
✔️ A DO egy köznapi nevet használ, például value
item
a típusnév ismétlése helyett olyan ritka esetekben, amikor egy azonosítónak nincs szemantikai jelentése, és a paraméter típusa nem fontos.
Meglévő API-k új verzióinak elnevezése
✔️ A DO a régi API-hoz hasonló nevet használ egy meglévő API új verzióinak létrehozásakor.
Ez segít kiemelni az API-k közötti kapcsolatot.
✔️ A DO előtag helyett utótagot szeretne hozzáadni egy meglévő API új verziójának jelzéséhez.
Ez segít a felderítésben a dokumentáció böngészésekor vagy az IntelliSense használatakor. Az API régi verziója az új API-k közelében lesz rendszerezve, mivel a legtöbb böngésző és az IntelliSense betűrendben jeleníti meg az azonosítókat.
✔️ FONTOLJA meg, hogy egy teljesen új, de értelmes azonosítót használjon utótag vagy előtag hozzáadása helyett.
✔️ A DO egy numerikus utótagot használ egy meglévő API új verziójának jelzésére, különösen akkor, ha az API meglévő neve az egyetlen értelmes név (azaz ha iparági szabvány), és ha bármilyen értelmes utótag hozzáadása (vagy a név módosítása) nem megfelelő lehetőség.
❌ NE használja az "Ex" (vagy hasonló) utótagot egy azonosítóhoz az azonos API korábbi verziójától való megkülönböztetéséhez.
✔️ A DO a "64" utótagot használja az API-k olyan verzióinak bevezetésekor, amelyek 32 bites egész szám helyett 64 bites egész számon (hosszú egész számon) működnek. Ezt a megközelítést csak akkor kell alkalmaznia, ha a meglévő 32 bites API létezik; ne tegye meg teljesen új, csak 64 bites verziójú API-k esetén.
© Részletek 2005, 2009 Microsoft Corporation. Minden jog fenntartva.
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, published 22, 2008 by Addison-Wesley Professional, a Microsoft Windows Development Series részeként.