|
|
|
Kaynak Kodunuzu XML ile Süsleyin |
|
| Gönderiliyor lütfen bekleyin... |
|
|
Büyük yazılım projelerinde en önemli aktivitelerden birisi proje bazında iyi
bir dökümantasyon yapmaktır; proje analiz sürecindeki dökümantasyon genellikle
standart olan UML diyagramları ile yapılmaktadır, tabi işin bir de geliştiriciye
bakan tarafı vardır. Projenin en nihayi sonu kod yazmak olduğuna göre kodların
dökümantasyonu da en az analiz sürecindeki dökümantasyon kadar önemlidir. Bu
yazıda .NET ile birlikte ön plana çıkan XML yorum formatı ile kodlarımızı nasıl
dökümante edebileceğimizi inceleyeceğiz.
Bildiğiniz gibi kodlarımıza yorum satırı koymamızdaki en büyük amaç kodların
başkası tarafından kolaylıkla anlaşılabilir hale gelmesini sağlamaktır. Bazen
bu işlemi kendimiz içinde yapmak durumunda kalabiliriz, zira bir çok karmaşık
uygulamada yazdığımız kaynak koda yıllar sonra belkide aylar sonra baktığımızda
vakt-i zamanında neler düşündüğümüz hemen aklımıza gelmeyebilir. Bu durumda
en büyük yardımcımız o zamanlar tembellik etmeden yazdığımız yorum satırları
olacaktır. Eğer kendinize yorum satırı ekleme alışkanlığını kazandırırsanız
bunun getirisini ileride mutlaka göreceksiniz. Peki ne kadar yorum satırı gereklidir?
Bu sorunun cevabı size ve yazdığınız kodların karmaşıklığına göre değişir. Eğer
şiir gibi kod yazıyorum diyorsanız belkide bir cümlelik yorum satırı işinizi
görebilir, yok arap saçı gibi kod yazıyorum diyorsanız belkide yazdığınız kod
satırı sayısından daha fazla yorum yazmak zorunda kalabilirsiniz.
.NET bir çok meselede olduğu gibi yorum ekleme mekanizmasını da estetik bir
şekilde çözmüştür. Çok değil daha bir kaç yıl öncesine kadar kaynak kodlarımızdaki
yorum satırları // ve /* */karekterleri ile belirtiliyordu. .NET bu eski yorum
yazma şeklini desteklemekle birlikte XML formatındaki yorum ekleme mekanizmasıyla
ön plana çıkmaktadır. XML sayesinde artık kodlarımızdaki yorumlar standart hale
getirilmiştir. Böylece bir XML yorumunda belirli bir etiketi gördüğümüzde o
etiketin içindeki açıklamanın neyi ifade ettiğini anlarız. Aynı zamanda VS.NET
kodlarımızdaki XML yorumlarını ayrıştırarak saf bir XML dosyası da üretebilmektedir.
Bu sayede XML formatındaki yorum dosyasını istediğimiz sistem ile rahatlıkla
entegre edebilirz, söz gelimi proje yöneticisine XML dosyasındaki yorum bilgilerini
HTML formatında sunabiliriz.
XML Yorum Satırları
C#'ta XML yorum satırları " /// (3 adet slash karakteri) " ile başlayan
satırlarda yazılır. Önceden belirlenmiş bir takım standart XML etiketleri vardır,
öyleki bu etiketler aynı zamanda ECMA tarafından da standart olarak kabul edilmiştir.
Ancak XML etiketlerini programcı istediği şekilde şirketin ihtiyaçlarına yada
kendi ihtiyaçlarına göre genişletebilir. XML yorum yazmadaki belkide tek kısıt
XML sözdizimine uyma şartıdır. XML sözdizimine göre açılan bütün etiketler kapanmalıdır.
En çok kullanılan önceden tanımlı XML etiketleri , ,
ve etiketleridir. Bu etiketlerin bazıları
intellisense ve "Object Browser" programı tarafından kullanılmaktadır.
Örneğin VS.NET editöründe bir nesne yaratıldığında nesne türüne ait yapıcı metottaki
parametrelerin kısa açıklaması editör penceresinde gösterilir. Aynı şekilde
kendi yazdığımız sınıflar içinde bu açıklamaların çıkmasını istiyorsak XML yorum
etiketlerini kullanmamız gerekir.
XML yorum etiketleri tür bazında, metot bazında ve parametre bazında olabilir.
Tür bazında yorum ekleme işlemi sınıflar, temcilciler, indeksleyiciler, olaylar,
numaralandırmalar(enums) ve yapılar(struct) için uygulanabilir. Metot bazındaki
yorumlar herhangi bir metodun bildiriminden önce yapılır. Parametre bazındaki
yorumlar ise bir metodun parametreleri ve geri dönüş değerleri ile ilgilidir.
Açıklayıcı olması açısından örnek bir sınıf üzerinde XML yorumlarını ve VS.NET
gibi akıllı editörlerde bu yorumların ne gibi etkilerinin olduğunu inceleyelim.
Şimdi yeni bir "Class Library" projesi açıp aşağıdaki sınıf bildirimini
yazın.
using
System;
namespace
XMLYorum
{
///
/// Cebir
sinifi bazi özel matematiksel islemleri
/// yapmak
için çesitli statik metotlar sunar.
///
public class
Cebir
{
///
///
Mutlak Deger Alma Islemi
///
///
///
Parametre olarak gelen sayinin
///
Mutlak Degerini alir.
///
///Mutlak Degeri alinacak
sayi.
///Paremetre
olarak gelen sayinin mutlak degeri.
public
static int MutlakDeger(int Deger)
{
if(Deger
< 0)
return
-Deger;
else
return
Deger;
}
///
///
Kare Alma Islemi
///
///
///
Parametre olarak gelen sayinin
///
karesini almak için kullanilir.
///
///Karesi alinacak
sayi.
///Parametre
olarak gelen sayinin karesi.
public
static double KareAl(double Deger)
{
return
Deger * Deger;
}
}
}
|
Yukarıdaki örnek
koddan görüldüğü üzere sınıf ve metot bildirimlerinden önce /// ile başlayan
satırlarda XML formatında yorumlar yazılmıştır.VS.NET kod editörü /// karakterinden
sonra , ve
etiketlerini otomatik oluşturdu. etiketini ise kendimiz yazmalıyız.
XML yorum etiketleri de intellisense özelliklerinden faydalanır. Otomatik tamamlama
işlemi etiketler içinde geçerlidir.
Yukarıdaki örnekte etiketi ile sınıf yada metod ile ilgili kısa
bir açıklama yapılır. etiketi içinde daha ayrıntılı bilgi verilir.
Gerekirse çeşitli teknik bilgiler de bu etiket içinde belirtilir.
Şimdi C# derleyicisinin XML formatındaki yorumları kaynak koddan ne şekilde
ayırdığını görmek için projeyi derleyelim. Projeyi derlemeden önce eğer VS.NET
kulllanıyorsanız Proje özellikleri(Solutin Explorer'a sağ tıklayarak görebilirsiniz)
penceresinden "Configuration Properties/Build" sekmesinin altındaki
"XML Documentation File" kutusuna oluşturulacak XML dosyasının ismini
aşağıdaki gibi yazmalısınız. Tabi VS.NET editörünün intellisense özelliklerinden
faydalanmak istiyorsak XML dosyasının ismini oluşturulacak DLL ismiyle aynı
verilmeliyiz.
Eğer VS.NET gibi akıllı bir editörünüz yoksa .NET Framework ile birlikte ücretsiz
olarak dağıtılan ve komut satırından çalıştırılabilen C# derleyicisini kullanarak
ta XML yorum dosyalarını oluşturabilirsiniz. Bunun için yapmanız gereken csc
derleyicisini komut satırından aşağıdaki gibi çalıştırmaktır.
csc /t:library /doc:XmlYorum.xml XmlYorum.cs
VS.NET yada C# komut satırı ile oluşturulan XML dosyasının yapısı aşağıdaki
gibidir.
Şimdi birde oluşturduğumuz Cebir isimli bir sınıfa farklı bir projeden referans
verip metotlarını kullanalım. Yeni bir Console uygulaması açın ve oluşturduğumuz
Cebir sınıfına ait assembly dosyasına referans verin. Eğer komut satırı derleyicisi
ile çalışıyorsanız " /r:Cebir.dll " parametresini ekleyin. Tabi bu
durumda XML yorumlarının etkisini göremeyeceksiniz. Çünkü XML yorumlarını göstermek
VS.NET teki akıllı editörün bir yeteneğidir. Notepad'in yada başka text editörlerinden
bu tür imkanlar beklememek lazım!
Cebir sınıfının KareAl() metodunu kullanmak istediğimizde VS.NET'teki kod editörü
bize KareAl() metoduna ilişkin XML formatındaki açıklamayı sarı kutucuk içinde
aşağıdaki gibi gösterecektir. Böylece kullanacağımız metodun veya sınıfın bildirimine
bakmamıza gerek kalmamıştır.
Aynı durum parametreler içinde geçerlidir. Örneğin KareAl() metodunun çağrım
parantezini yazdığımız anda aktif parametre ile ilgili XML açıklaması aşağıdaki
gibi gösterilir.
Aynı XML yorumları VS.NET ile entegre çalışan "Object Browser" arayüzü
ile de aşağıdaki gibi gösterilmektedir.
Not : "Object
Browser" penceresine erişmek için (Ctrl + Alt + J) tuş kombinasyonunu kullanabilirsiniz.
Diğer XML Yorum Etiketleri
XML yorum etiketleri yukarıda anlatılanlar ile sınırlı değildir. Aşağıda kullanılabilecek
standart etiketler alfabetik sıraya göre toplu bir şekilde tablo halinde açıklamalarıyla
birlikte verilmiştir.
|
Açıklama
içindeki bir bölümün "kod fontu" şeklinde olduğunu vurgulmak için
kullanılır.
Örnek :
///
/// Bu sınıf Stream
sınıfından türemiştir.
///
public class YeniSınıf
{
...
}
|
|
XML
açıklaması içinde uzun bir kod bloğu örneği verilecekse diğer yazılardan
ayırmak için kod bloğu bu etiket arasında yazılır.
Örnek :
///
/// Bu metod iki Kompleks türeden sayıyı toplar.
Örneğin
///
/// Kompleks sayi1 =
new Kompleks(5,6);
/// Kompleks sayi2 =
new Kompleks(0,1);
///
/// Kompleks sayi3 =
sayi1 + sayi2;
///
///
public Kompleks operator+(Kompleks
sayi1, Kompleks sayi2)
{
...
}
|
|
Bir
metodun yada sınıfın ne şekilde kullanılacağını açıklayan blok bu etiket
içinde yazılır. etiketinin kullanımı ile hemen hemen eşdeğerdedir.
etiketini verilen örneğin aynısı etiketi içinde
geçerli olduğu ayrıca bir örnek vermeye gerek yoktur. |
|
Bir
metodun fırlatabileceği istisnai durumlarla ilgili bilgi vermek için kullanılır.
etiketi "cref" niteliği ile birlikte kullanılır.
"cref" niteliği ile fırlatılacak istisnai durum(exception) sınfının
türü belirtilir.
Örnek :
///
/// Bu metod iki Kompleks türeden sayıyı toplar.
Örneğin
///
///
///
///
///
///
public Kompleks operator+(Kompleks
sayi1, Kompleks sayi2)
{
...
}
|
|
HTML kodlarındaki
etiketine benzer bir amacı vardır. Liste şeklinde bir yapı
oluşması gerektiği bildirilir. listedeki başlık bilgisini,
- listedeki her elemanı, her elemandaki terimi
ve bu eleman hakkındaki detaylı bilgiyi bildirir.
Örnek :
/// Bu
bir liste örneğidir.
///
///
///
///
///
/// term
1
/// Açıklama
1
///
///
///
///
/// term 2
/// Açıklama
2
///
///
///
/// term 3
/// Açıklama
3
///
///
///
///
public class YeniSınıf
{
...
}
Not : Liste tipi(
)
"number" olabileceği gibi "bullet" ve "table"
da olabilir.
|
|
gibi uzun açıklama bloklarında bir paragrafı belirtmek için kullanılır.
Örnek :
///
/// Bu sınıf Stream
sınıfından türemiştir.
///
/// Bu sınıf aynı zamanda IDisposable arayüzünü
uygulamıştır.
///
///
public class YeniSınıf
{
...
}
|
|
Bir
metodun parametreleri ile ilgili bilgi vermek için kullanılır.
Örnek :
///Toplanacak
birinci sayı
///Toplanacak
ikinci sayı
public static double Topla(int
Sayi1, int Sayi2)
{
return Sayi1
+ Sayi2;
} |
|
etiketleri içerisine alınan yerde aslında metodun ilgili parametresinin
olduğu bildirilir. Böylece oluşacak XML yorum dosyasınıdaki bu etiketi farklı
bir biçimde yorumlama şansına sahip oluruz.
Örnek :
///
/// Bu sınıfın , ve
/// ve biçiminde iki
parametresi vardır.
///
public static double Topla(int
Sayi1, int Sayi2)
{
return Sayi1
+ Sayi2;
} |
|
Üye
elemanla ilgili güvenlik bilgisi vermektedir. Örneğin bir metoda yada sınıfa
kimlerin erişeceği ve ne şekilde erişeceği bu etiket kullanılarak belirtilebilir.
Örnek :
///Herkes
bu metoda erişebilir.
///
public static double Topla(int
Sayi1, int Sayi2)
{
return Sayi1
+ Sayi2;
} |
|
Bir
tür hakkında kısa bir açıklama vermek için kullanılır.
Örnek :
///
/// Özel cebirsel işlemleri
tanımlar.
///
public class Cebir
{
....
} |
|
Bir
metodun geri dönüş değeri ilgili bilgi vermek için kullanılır.
Örnek :
///
/// Kare Alma Islemi
///
///
/// Parametre olarak
gelen sayinin
/// karesini almak için
kullanilir.
///
///Karesi
alinacak sayi.
///Parametre
olarak gelen sayinin karesi.
public static double KareAl(double
Deger)
{
return
Deger * Deger;
} |
|
Yazı
içinde bir bağlantının(link) olacağını belirtir. "cref" niteliği
ile birlikte kullanılır. "cref" niteliği bağlantının olacağı üye
elemanı simgeler.
Örnek :
///
/// Bu metod iki Kompleks türeden sayıyı toplar.
Örneğin
///
///
///
public Kompleks operator+(Kompleks
sayi1, Kompleks sayi2)
{
...
} |
|
Yazı
içinde ilgili elemanla yakından ilişkili olan diğer elemanlara bağlantı
vermek için kullanılır. Kullanımı etiketi ile aynıdır.
Örnek :
///
/// Bu metod iki Kompleks türeden sayıyı toplar.
Örneğin
///
///
///
///
///
public Kompleks operator+(Kompleks
sayi1, Kompleks sayi2)
{
...
} |
|
Üye
elemanla ilgili geniş açıklama yazmak için kullanılan bir etikettir.
Örnek :
///
/// Cebir sinifi bazi
özel matematiksel islemleri
/// yapmak için çesitli
statik metotlar sunar.
///
public class Cebir
{
...
} |
|
Sınıfın
bir üye elemanı olan özellikler (Property) hakkında bilgi vermek için kullanılır.
Örnek :
///
/// Kontrolün rengini
belirtir.
///
public int Renk
{
get { return
a;}
set { a = value;}
} |
Kodlarınızı XML
yorumları ile süslemiyi unutmayın !...
Makale:
Kaynak Kodunuzu XML ile Süsleyin C#, Visual C# ve .NET Sefer Algan
|
|
|
|
|
-
-
Eklenen Son 10
-
Bu Konuda Geçmiş 10
Bu Konuda Yazılmış Yazılmış 10 Makale Yükleniyor
Son Eklenen 10 Makale Yükleniyor
Bu Konuda Yazılmış Geçmiş Makaleler Yükleniyor
|
|
|