C# İsimlendirme Kılavuzu

.NET geliştirmelerinde kullanılmak üzere belirli ve tutarlı bir isimlendirme ve biçimlendirme kılavuzu sağlaması hedeflenir.

1. Giriş

1.1 Amaç

Bu belgenin amacı .NET geliştirmelerinde kullanılmak üzere belirli ve tutarlı bir isimlendirme ve biçimlendirme kılavuzu sağlayarak, kolay anlaşılabilir kod üretilmesine ve uygulama çapında biçimsel bir bütünlüğün sağlanmasına yardımcı olmaktır.

1.2 Kaynaklar

Bu belge oluşturulurken Microsoft’un Naming Guidelines içeriğinden faydalanılmıştır.

1.3 Referanslar

Naming Guidelines, http://msdn.microsoft.com/en-us/library/ms229002.aspx

2. İsimlendirme

2.1 Baş harf yazım biçimleri

Kullanılması uygun iki farklı baş harf yazım biçimi vardır:

PascalCasing İsmin ilk harfi ve birleştirilen her kelimenin ilk harfi büyüktür. Parametre isimleri hariç tüm isimler için kullanılabilir. (İki harften uzun kısaltmalar dahil.)

OrderPayment HtmlTag

İki harften oluşan kısaltmaların özel biri durumu vardır. İki harf de büyük yazılır. (Tartışılabilir)

IOStream

camelCasing

İsmin ilk harfi küçük, birleştirilen her kelimenin ilk harfi büyüktür. Sadece parametre isimleri için kullanılır.

orderPayment htmlTag

İki harften oluşan kısaltmalarda iki harf de küçüktür.

ioStream

Public elemanlar, tipler ve birden fazla kelimeden oluşan isim alanları için PascalCasing kullanın.

Parametre isimleri için camelCasing kullanın.

Belirteç	Yazım Biçimi	Örnek
Namespace	Pascal	namespace System.Security { ... }
Type	Pascal	public class StreamReader { ... }
Interface	Pascal	public interface IEnumerable { ... }
Method	Pascal	public class Object { public virtual string ToString();}
Property	Pascal	public class String { public int Length { get; }}
Event	Pascal	public class Process { public event EventHandler Exited;}
Field	Pascal	public class MessageQueue { public static readonly TimeSpan InfiniteTimeout;} public struct Int32 { public const Min = 0;}
Enum value	Pascal	public enum FileMode { Append, Read}
Parameter	Camel	public class Convert { public static int ToInt32(string value);}

Bileşik kelimeler ve genel terimler

• Çoğu bileşik kelime, baş harf yazım biçimi için tek bir kelime gibi işlem görür.

• Bileşik kelimelerin içerdiği her kelimenin baş harfini büyük yazmayın.

• Bileşik kelimelerin tespiti için bir sözlük kullanılabilir.

Bazı bileşik kelimeler ve genel kullanılan ifadelerin listesi

Pascal	Camel	Yanlış
BitFlag	bitFlag	Bitflag
Callback	callback	CallBack
Canceled	canceled	Cancelled
DoNot	doNot	Don't
Email	email	EMail
Endpoint	endpoint	EndPoint
FileName	fileName	Filename
Gridline	gridline	GridLine
Hashtable	hashtable	HashTable
Id	id	ID
Indexes	indexes	Indices
LogOff	logOff	LogOut
LogOn	logOn	LogIn
Metadata	metadata	MetaData, metaData
Multipanel	multipanel	MultiPanel
Multiview	multiview	MultiView
Namespace	namespace	NameSpace
Ok	ok	OK
Pi	pi	PI
Placeholder	placeholder	PlaceHolder
SignIn	signIn	SignOn
SignOut	signOut	SignOff
UserName	userName	Username
WhiteSpace	whiteSpace	Whitespace
Writable	writable	Writeable

Hungarian (Macar) Notasyonu Macar notasyonu değişken isimlerinin veri tiplerini içerecek şekilde tanımlandığı bir isimlendirme şemasıdır. Belgelendirme ve isimlendirmenin bir arada kullanıldığı bir isimlendirme tekniğidir.

Örnek:

strFirstName iNumberOfDays

Macar notasyonunun kullanılması önerilmez. Kullanılacaksa ancak özel ve yerel değişkenler için kullanılabilir. Public değişkenler, özellikler veya metot parametrelerinde kullanılmamalıdır.

2.2 Genel İsimlendirme Kuralları

Kelime Seçimi

• Kolay okunabilir isimler seçin.

  • Örneğin, HorizontalAlignment adlı bir özellik, AlignmentHorizontal isminden daha kolay okunabilir bir yapıdadır. (İngilizce için)

• Kısa olmaya değil, açık olmaya gayret edin.

  • CanScrollHorizontally adlı bir özellik, ScrollableX (X-eksenine belirsiz bir referans) isminden daha iyidir.

• Alt çizgi, tire veya alfanümerik olmayan bir karakter kullanmayın.

• Macar notasyonu kullanmayın.

• Programlama dillerinde yaygın olarak kullanılan anahtar kelimelerden kaçının.

Kısaltmalar

• İsimlerin sadece bir parçasından oluşan, kelime sadeleştirme amaçlı kısaltmalar kullanmayın.

  • Örneğin GetChan yerine GetChannel olarak isimlendirin.

• Yaygın olarak kabul edilmemiş kısaltmalar (kelimelerin baş harflerinden oluşan) kullanmayın ya da yaygınlarsa bile sadece gerektiğinde kullanın.

Dile Özel İsimler

• Dile özel kelimeler yerine anlamsal olarak seçilen kelimeler kullanın.

  • Örneğin, GetLength adı GetInt adından daha iyidir.

• İsmin tipinden başka anlamsal bir ifadesi bulunamıyorsa, isimlendirmede dile özel tip adı değil CLR tip adı kullanın. Örneğin, Int64 tipine çevirme işlemi yapan bir metot ToInt64 olarak isimlendirilmelidir, ToLong olarak değil. Çünkü Int64, C# diline özel tanımlanmış long ifadesini belirten CLR tipidir. Aşağıdaki tablo CLR tip adlarını kullanan temel veri tiplerini içerir (karşılık gelen C#, Visual Basic ve C++ tip adlarıyla birlikte).

C#	Visual Basic	C++	CLR
sbyte	SByte	char	SByte
byte	Byte	unsigned char	Byte
short	Short	short	Int16
ushort	UInt16	unsigned short	UInt16
int	Integer	int	Int32
uint	UInt32	unsigned int	UInt32
long	Long	__int64	Int64
ulong	UInt64	unsigned __int64	UInt64
float	Single	float	Single
double	Double	double	Double
bool	Boolean	bool	Boolean
char	Char	wchar_t	Char
string	String	String	String
object	Object	Object	Object

Mevcut API’lere ait yeni versiyonların isimlendirilmesi

• Mevcut bir API’nin yeni versiyonunu oluştururken eski API’ye benzer bir isim kullanın. Bu, API’lerin arasında ilişkiyi vurgulamaya yardımcı olur.

• Yeni API oluştururken önek yerine sonek kullanmayı tercih edin. Bu teknik belgelendirme incelenirken veya Intellisense kullanılırken ilişkili API’lerin yakın olmasına yardımcı olur.

• Önek veya sonek kullanmak yerine tamamen yeni ama anlamlı bir isim kullanmayı düşünün.

• Mevcut API’nin adının aynı kalması tek seçenekse, yeni versiyonu belirten nümerik bir sonek kullanın. Eski API’yi belirtmek için “Ex” benzeri sonekler kullanmayın.

• 32-bit yerine 64-bit integer ile çalışan yeni API versiyonlarını oluştururken “64” sonekini kullanın. Bunu sadece mevcut 32-bit API varsa yapın. Sadece 64-bit versiyonu olan yeni API’ler için yapmayın.

2.3 Kütüphane ve DLL İsimleri

• DLL isimleri için geniş işlevsellik gruplarını temsil eden isimler seçin. Örneğin, System.Data. Kütüphane isimleri ile isim uzayları örtüşmek zorunda değildir, ama kütüphaneleri isimlendirirken isim uzaylarını takip etmek yararlıdır. Genel bir kural, kütüphanenin içerdiği en genel öneki kullanarak kütüphaneyi isimlendirmektir. Örneğin, System.Data.SqlServer ve System.Data.SqlServerCompact isim alanlarını içeren kütüphane için System.Data ismi.

• Kütüphaneleri isimlendirirken aşağıdaki kalıbı kullanmayı düşünün: <Company>.<Component>.dll <Component> bir veya daha fazla nokta ile ayrılan bölüm içerebilir. Örneğin:

Litware.Controls.dll

2.4 İsim Uzaylarının İsimleri

Aşağıdaki şablon isim uzaylarını isimlendirirken kullanılabilecek genel kuralı ifade eder:

<Company>.(<Product>|<Technology>)[.<Feature>][.<Subnamespace>]

Örnekler:

Fabrikam.Math Litware.Security

• İsim uzaylarının isimlerinin diğer firmaların aynı adlı isim uzaylarıyla karışmaması için firma adını önek olarak kullanın.

• İsim uzayının ikinci seviyesinde versiyon bağımsız ürün adını kullanın.

• İsim uzayı hiyerarşilerinde organizasyonel hiyerarşileri kullanmayın, çünkü firmalardaki grup adları kısa ömürlüdür. İsim uzaylarının hiyerarşisini ilişkili teknolojilerin gruplarına göre düzenleyin.

• PascalCasing kullanın ve farklı isim uzayı bileşenlerini nokta ile ayırın.

2.5 Sınıf, Struct ve Arayüzlerin İsimleri

• Sınıf ve struct isimleri için adlar veya ad ifadeleri kullanın (PascalCasing ile). Bu, tip isimlerini, fiil ifadelerinden oluşan metot isimlerinden ayırır.

• Arayüzlerin isimleri için sıfatlar veya nadir olarak ad veya ad ifadeleri kullanın. Ad veya ad ifadeleri kullanmanın mantıklı görünmesi, tipin arayüzden ziyade abstract bir sınıf olması gerektiğine işaret edebilir.

• Sınıf isimlerinde önek kullanmayın (Örneğin, “C”).

• Türemiş sınıfın adını, temel sınıf adı ile bitirmeyi düşünün. Bu teknik okunabilirliği arttırır ve ilişkiyi açık bir şekilde ifade eder. Bazı örnekler:

  • ArgumentOutOfRangeException (temel tip Exception)

  • SerializableAttribute (temel tip Attribute)

• Bu tekniği kullanma kararı, durum için mantıklı olup olmadığını değerlendirme sonucunda verilebilir. Örneğin, Button sınıfının ana sınıfı Control sınıfıdır, ancak isminin sonunda bu ismi kullanmaz.

• Arayüz isimleri için “I” önekini kullanın. Bu önek, tipin bir arayüz olduğunu göstermek için kullanılır.

  • Örneğin, IComponent (ad), ICustomAttributeProvider (ad ifadesi) ve IPersistable (sıfat) arayüz isimleri için uygun isimlerdir. Diğer tip isimlerinde olduğu gibi, kısaltmalardan kaçının.

• Sınıfın, arayüzün standart uygulaması olduğu bir sınıf-arayüz çifti tanımlarken, isimlerin sadece “I” öneki ile farklılaştığından emin olun.

Generic Tip Parametreleri

• Tek harfli ismin tamamıyla anlaşılabilir olduğu ve açıklayıcı bir ismin ek bir değer oluşturmadığı durumlar hariç, generic tip parametreleri için açıklayıcı isimler kullanın.

• Tek harfli tip parametreleri için T ismini kullanmayı düşünün.

public int IComparer<T> { ... }

public delegate bool Predicate<T>(T item);

public struct Nullable<T> where T:struct { ... }

• Açıklayıcı tip parametresi isimleri için T önekini kullanın.

public interface ISessionChannel where TSession : ISession
{
        TSession Session { get; }
}

• Tip parametresine konan kısıtları göstermek için tip parametresi adını kullanmayı düşünün. Örneğin, ISession tipinin kullanılması gereken parametre TSession olarak isimlendirilebilir.

Genel Tiplerin İsimleri

.NET framework tiplerinden türetilen tipleri isimlendirirken aşağıdaki tabloda belirtilen önerileri takip edin.

Temel Tip Türetilen Tip Kılavuzları

System.Attribute Özel attribute sınıflarının isimlerinde “Attribute” sonekini kullanın.

System.Delegate Olaylarda kullanılan delegelerin isimlerinde “EventHandler” sonekini kullanın. Olay işleyiciler olarak kullanılmayan delegelerin isimlerinde “Callback” sonekini kullanın. Bir delege için “Delegate” sonekini kullanmayın.

System.EventArgs “EventArgs” sonekini kullanın.

System.Enum Bu sınıftan türetme yapmayın. Dilinizin desteklediği anahtar kelimeyi kullanın; örneğin C# için enum anahtar kelimesini kullanın. “Enum” veya “Flag” sonekini kullanmayın.

System.Exception “Exception” sonekini kullanın.

IDictionary IDictionary<TKey,TValue> “Dictionary” sonekini kullanın. IDictionary belirli bir kolleksiyon tipidir, ancak bu kılavuz takip eden daha genel kolleksiyonlara dair kılavuza göre önceliğe sahiptir.

IEnumerable ICollection IList IEnumerable<T> ICollection<T> IList<T> “Collection” sonekini kullanın.

System.IO.Stream “Stream” sonekini kullanın.

CodeAccessPermission IPermission “Permission” sonekini kullanın.

Enumerasyonları İsimlendirmek

Enumerasyonları isimlendirirken standart tip isimlendirmesi (PascalCasing) kullanılır.

• Enumerasyon adı için tekil isim kullanın (değerlerin bit alanlar olması hariç durumlarda).

• Değerleri bit alanları olan enumerasyonlar için çoğul isimler kullanın (flags enum olarak da adlandırılır).

• Enumerasyon tipleri için “Enum” sonekini kullanmayın.

• Enumerasyon tipleri için “Flag” veya “Flags” sonekini kullanmayın.

• Enumerasyon değer isimlerinde önek kullanmayın (Örneğin, ADO enumerasyonları için “ad”, rich text enumerasyonları için “rtf” gibi).

2.6 Tip Elemanlarının İsimleri

Tipler elemanlardan oluşur: metotlar, özellikler, yapıcı metotlar ve alanlar.

Metot İsimleri

Metot isimleri için fiil veya fiil ifadeleri kullanın.

public class String {

    public int CompareTo(...);
    
    public string[] Split(...);
    
    public string Trim();
    
}

Özellik İsimleri

• Özellik isimleri için PascalCasing kullanın.

• Özellik isimleri için ad, ad ifadesi veya sıfat kullanın.

• “Get” metotları ile eşleşen özellikler tanımlamayın.

public string TextWriter 
{ 
    get {...} 
    set {...} 
}

public string GetTextWriter(int value) 
{ 
    ... 
}

Bu kalıp, özelliğin aslında bir metot olması gerektiğini gösterir.

• Koleksiyon tipinden özellikleri isimlendirirken, tekil bir ifade kullanıp sonuna “List” veya “Collection” kelimesini eklemek yerine, elemanları tanımlayan çoğul bir ifade kullanın.

• Boolean özellikleri isimlendirmek için olumlu bir ifade kullanın. (CantSeek yerine CanSeek) Tercihen “Is”, “Can” veya “Has” önekleri de kullanılabilir, ama sadece bir değer katıyorsa.

• Bir özelliğe tipi ile aynı ismi verme seçeneğini düşünün. Örneğin, aşağıdaki özellik, Color adlı enumerasyon değerini döndüren ve bu değere atama yapan işlevlere sahip. Demek ki Color olarak isimlendirilebilir:

public enum Color 
{
    ...
}

public class Control {
    public Color Color 
    { 
        get {...} 
        set {...} 
    }
}

Olay İsimleri

• Olayları isimlendirirken fiil veya fiil ifadeleri kullanın. Clicked, Painting, DroppedDown vb.

• Olayları isimlendirirken şimdiki ve geçmiş zamanı kullanarak, önce ve sonra kavramlarını kullanın. Örneğin, bir pencere kapatılmadan önce oluşan olay Closing, pencere kapatıldıktan sonra oluşan olay Closed olarak isimlendirilir.

• Önce ve sonra olaylarını belirtmek için “Before” veya “After” gibi ekler kullanmayın.

• Olay işleyicileri (olay tipinde kullanılan delegeler) isimlendirirken EventHandler sonekini kullanın.

public delegate void ClickedEventHandler(object sender, ClickedEventArgs e);

• Olay işleyicilerde sender ve e adlı iki parametre kullanın.

• Olay argümanı sınıflarını isimlendirirken “EventArgs” sonekini kullanın.

Alan İsimleri

• Private, protected ve yerel alan isimleri için camelCasing kullanın.

• Alanları isimlendirirken ad, ad ifadesi veya sıfat kullanın.

• Tek karakterli isimler kullanmayın (örneğin, tam sayılar için i, j, k, m, n, karakterler için c, d, e).

• Alanları isimlendirirken önek kullanmayın. Örneğin, statik alanları ifade etmek için “g_” veya “s_” veya private alanlar için “_” öneklerini kullanmayın.

• Sabit (constant) alanları isimlendirirken PascalCasing kullanın.

private const int TheAnswer = 42;

2.7 Parametreleri İsimlendirmek

• Parametre isimleri için camelCasing kullanın.

• Parametreler için açıklayıcı isimler kullanın.

• Parametrenin tipini değil, parametrenin anlamını temel alan isimler kullanın.

2.8 Kaynakları İsimlendirmek

Yerelleştirme kaynaklarına belirli nesnelerin özellikleri gibi ulaşıldığından, yerelleştirme kaynaklarının isimlendirme kılavuzları özelliklerin isimlendirme kılavuzlarına benzer.

• Kaynak anahtarları için PascalCasing kullanın.

• Kısa belirteçler yerine açıklayıcı isimler kullanın.

• Ana CLR dillerine ait dile özel anahtar kelimeler kullanmayın.

• Kaynakları isimlendirirken sadece alfanümerik karakterler ve alt çizgiler kullanın.

• Hata mesajı kaynaklarını isimlendirirken aşağıdaki isimlendirme kalıbını kullanın. Kaynak belirteci “hata tipi adı” + “hatayı belirten kısa bir ifade” olmalıdır.

ArgumentExceptionIllegalCharacters ArgumentExceptionInvalidName ArgumentExceptionFileNameIsMalformed

2.9 Projeleri İsimlendirmek

Solüsyonun ismi için projeyi belirten ana ifade kullanılır.

ECommerce

Solüsyonun içerdiği projeler, istisnai bir durum yoksa solüsyon ismi ile başlar ve projenin adı ile devam eder.

• ECommerce (Solution)

  • ECommerce.Business

  • ECommerce.Data

  • ECommerce.Ioc

  • ECommerce.Model

  • ECommerce.UI

Proje ile ilişkili alt projeler, ilişkili olduğu ana projenin ismiyle başlar ve kendi ismiyle devam eder.

• ECommerce.Data.Model

• ECommerce.UI.Library

• ECommerce.UI.Library.Model

Projelerin solüsyondaki isimleriyle fiziksel dizin isimlerinin aynı olması beklenir.

Solution Folder Visual Studio uygulamasında “Solution Folder” oluşturularak projeler sanal olarak gruplanabilir. Bu gruplama fiziksel yapıyı etkilemez. Solution folder oluşturulurken Solüsyon adının önek olarak kullanılmasına gerek yoktur. Grubu belirten ana ifadeyle “Solution folder” oluşturulabilir.

• ECommerce (Solution)

  • ECommerce.Business (Proje)

  • Data (Solution Folder)

    • ECommerce.Data (Proje)

    • ECommerce.Data.Model (Proje)

  • ECommerce.Ioc (Proje)

  • ECommerce.Model (Proje)

  • UI (Solution Folder)

    • ECommerce.UI (Proje)

    • ECommerce.UI.Library (Proje)

    • ECommerce.UI.Library.Model (Proje)

2.10 Uygulama Bileşen İsimleri

Uygulamada bir bileşen adının belirtilmesi gerektiğinde literal string yerine bu adları içeren özel, statik sınıflar kullanılır. Bu sınıfların ve özelliklerinin isimlendirmesinde PascalCasing kullanılır.

Web

Name	Value
View adları	Foo.Web.Library.ViewNames
Partial View adları	Foo.Web.Library.PartialViewNames
E-posta şablonları	Foo.Framework.Model.MailTemplateViewNames
Controller adları	Foo.Web.Library.ControllerNames
Action metot adları	Foo.Web.Library.XControllerActionNames.cs
Route adları	Foo.Framework.RouteNames
Route oluşturulurken kullanılan parametre adları	Foo.Web.Library.Model.WebParameterNames
Css sınıf adları	Foo.Web.Library.Model.CssClassNames
TempData Key adları	Foo.Web.Library.Model.TempDataKeyNames
Cookie adları	Foo.Web.Library.Model.CookieNames

Data

Name	Value
SQL Stored Procedure adları	Foo.Data.StoredProcedures
SQL Kolon adları	Foo.Api.Data.ColumnNames
SQL Stored Procedure Parametre adları	Foo.Api.Data.SqlParameterNames

Örnek:

public static class PartialViewNames
{
	public static string _Friend
	{
		get
		{
			return nameof(_Friend);
		}
	}
}

Eski ve yeni kullanımlar:

//eski
return View("LogOn", model);

//yeni
return View(ViewNames.LogOn, model);

Sayfa adreslerinin küçük harfle oluşturulması için Controller ve Action adları küçük harfle oluşturulur:

public static string LogOn
{
	get
	{
		return nameof(LogOn).ToLowerInvariant();
	}
}

Süreç:

• Daha önce Enumeration kullanımı denendi ancak yazımın iyice uzaması nedeniyle statik sınıf kullanımına geçildi.

• Stored Procedure adları Resource dosyalarında tutuluyordu, bunlar da statik sınıfa taşındı.

3. Biçimlendirme

Bu bölümdeki öneriler kod okunabilirliğini arttırmak ve görsel tutarlılığı sağlamak amaçlıdır.

• Her satıra sadece bir ifade yazın.

• Metotların arasında bir satır boşluk bırakın.

• return ifadelerinden önce bir satır boşluk bırakın.

• if, for, foreach, switch, while bloklarından önce ve sonra birer satır boşluk bırakın.

• if bloğunun gövdesi bir satırdan oluşsa bile, süslü parantez ile blok oluşturun.

• Sınıf, metot gövdesini başlatan parantez için yeni bir satıra geçin. Bloğu başlatan ve bitiren parantezleri simetrik olarak kullanın.

• Yorumlardan önce bir satır boşluk bırakın ve yorumu açıklanan bölümün hemen üstündeki satıra yerleştirin.

• İlişkili metotları regionlarla gruplayın. (Bir sınıftaki region sayısı artarsa çok fazla sorumluluk üstlendiğinin işaretidir. SRP prensibi ihlal edilmiş olabilir. Region içerikleri yeni oluşturulacak sınıf adaylarıdır.)

Örnek:

public ServiceResult AddFriend(int requestSenderMemberId, int requestReceiverMemberId)
{
	//arkadaşlık benzersiz id bilgisini oluştur
	string friendshipUniqueId = idGeneratorService.CreateFriendshipUniqueId(requestSenderMemberId, requestReceiverMemberId);

	//arkadaşlık kaydını oluştur
	bool addFriendshipSucceeds = friendRepository.AddFriendship(requestSenderMemberId, requestReceiverMemberId, friendshipUniqueId);

	//arkadaş ekleme işlemi başarısızsa hata fırlat
	if (!addFriendshipSucceeds)
	{
		logger.LogError(
			SetMethodNameForLogMessage(nameof(AddFriend)),
			$"Arkadaşlık oluşturma işleminde beklenmeyen hata. İstek yapan Üye Id: {requestSenderMemberId}, İstek yapılan Üye Id: {requestReceiverMemberId}");

		return ServiceResult.Error("Arkadaşlık oluşturma işleminde hata oluştu.");
	}

	SendNewFriendshipNotification(requestSenderMemberId, requestReceiverMemberId);

	return ServiceResult.Success();
}

void SendNewFriendshipNotification(int requestSenderMemberId, int requestReceiverMemberId)
{
	var notificationService = notificationServiceFactory.CreateInstance();
	notificationService.SendNewFriendshipNotification(requestSenderMemberId, requestReceiverMemberId);
}