Bir programcının dünyası

C# ile Uygulama Geliştirirken Yorum Satırlarını Kullanmak yazımda başladığım konuya XML Dokümantasyonunu eklemem gerekir.

Geleneksel C-tarzı yorum satırlarına ilave olarak C# geliştirilen kodların Xml Dokümantasyonunu otomatik olarak çıkartabilmek için, güçlü yorum operatörlerine sahiptir.

Bu yorum operatörleri (///) ile başlayan satırlara yazılır.

Aşağıdaki listedeki operatörler, derleyici (compiler) tarafından tanınır ve desteklenir;

<c> Tek satırı C# kodu olarak işaretler. Örneğin: <c>string AdSoyad = “Engin Polat”;</c>
<code> Birden çok satırı C# kodu olarak işaretler.
<example> İlgili satırları “örnek kod” olarak işaretler.
<exception> Exception sınıfını dokümante eder. (Derleyici(compiler) tarafından kontrol edilir)
<include> Başka bir dokümantasyon dosyasından yorum ekler. (Derleyici(compiler) tarafından kontrol edilir)
<list> Dokümantasyona liste ekler.
<param> Method parametresini dokümante eder. (Derleyici(compiler) tarafından kontrol edilir)
<paramref> Kelimenin parametre olduğunu işaretler. (Derleyici(compiler) tarafından kontrol edilir)
<permission> Öğeye erişim belirleyicisini dokümante eder. (Derleyici(compiler) tarafından kontrol edilir)
<remarks> Öğeye açıklama ekler.
<returns> Method’un dönüş tipini dokümante eder.
<see> Başka bir parametreye çapraz-referans ekler. (Derleyici(compiler) tarafından kontrol edilir)
<seealso> Açıklamaya “buna da bakın” parçası ekler. (Derleyici(compiler) tarafından kontrol edilir)
<summary> Öğenin kısa açıklamasını dokümante eder.
<value> Özelliği (property) tanımlar.

Örnek olması açısından, aşağıdaki Matematik sınıfını dokümantasyonu ile birlikte yazıyorum;

//Matematik.cs
namespace Engin.Polat
{
	///<summary>
	///  Engin.Polat.Matematik sınıfı.
	///  İki rakamın toplanmasına yaran
	///  Topla method'unu içerir.
	///</summary>
	public class Matematik
	{
		///<summary>
		///  İki rakamın toplanmasını sağlar.
		///</summary>
		///<example>Örnek olarak: Topla(3, 5);</example>
		///<returns>Toplama işleminin sonucu (int)</returns>
		///<param name="x">Toplama işleminin ilk rakamı</param>
		///<param name="y">Toplama işleminin ikinci rakamı</param>
		public int Topla(int x, int y)
		{
			return x + y;
		}
	}
}

Derleme sonucu oluşan Xml dokümanı aşağıdaki gibidir;

<?xml version="1.0"?>
<doc>
	<assembly>
		<name>ConsoleApplication4</name>
	</assembly>
	<members>
		<member name="T:Engin.Polat.Matematik">
			<summary>
				Engin.Polat.Matematik sınıfı.
				İki rakamın toplanmasına yaran
				Topla method'unu içerir.
			</summary>
		</member>
		<member name="M:Engin.Polat.Matematik.Topla(System.Int32,System.Int32)">
			<summary>
				İki rakamın toplanmasını sağlar.
			</summary>
			<example>Örnek olarak: Topla(3, 5);</example>
			<returns>Toplama işleminin sonucu (int)</returns>
			<param name="z">Toplama işleminin ilk rakamı</param>
			<param name="y">Toplama işleminin ikinci rakamı</param>
		</member>
	</members>
</doc>

Dikkat ederseniz, derleyici (compiler) bizim için ve elementlerini eklemiştir. Her element’i name özelliğine sahiptir ve değer olarak öğenin tam adını içerir.

Değerin ilk harfi özel bir anlam taşır;

T : Type
F : Field
M : Member

Bu yazımda aslında çok kolay bir konuyu işliyor olacağım, C# kodunuza yorum satır(lar)ı eklemek.

Bu konuyu yazmamdaki asıl amacım, BilgeAdam‘daki öğrencilerim için hatırlatma niteliğinde olmasıdır.

C# geleneksel C-tarzı yorum satır(lar)ını destekler; (// …) veya (/* … */)

// Bu satır örnek olarak yorum haline getirilmiştir.
/* Bu satır örnek olarak yorum haline getirilmiştir. */

Tek satır yorum operatörünün (//) satırda buluduğu noktadan satırın sonuna kadar herşey yorum olarak kabul edilir.

Çok satır yorum operastöründe (/* */), başlangıç operatöründen (/*) bitiş operatörüne (*/) kadar herşey yorum olarak kabul edilir.

Tek satırlı ve çok satırlı yorumlar şu şekilde yazılabilir;

// Tek satırlı yorum
/* Bu satırlar
çok satırlı yorum
için iyi bir örnektir. */

Aşağıdaki kod’da geçerlidir;

Console.WriteLine(/* İşte yorum! */ “Kodun burası derlenir.”);

Aynı zamanda aşağıdaki gibi kodlar sayesinde, satır içerisinde kod parçalarına yorum yazabilmek mümkündür;

EkranaCiz(Boy, /* Yukseklik */ 250);

Tabiki string karakterleri arasındaki yorum operatörleri, normal karakter olarak değerlendirilecektir;

string mesaj = “/* Bu normal bir metin değişkenidir */”;