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 <param>, <remarks>, <summary> ve <returns> 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
{
      ///<summary>
      /// Cebir sinifi bazi özel matematiksel islemleri
      /// yapmak için çesitli statik metotlar sunar.
      ///</summary>
      public class Cebir
      {
            /// <remarks>
            /// Mutlak Deger Alma Islemi
            ///</remarks>
            ///<summary>
            /// Parametre olarak gelen sayinin
            /// Mutlak Degerini alir.
            ///</summary>
            ///<param name=”Deger”>Mutlak Degeri alinacak sayi.</param>
            ///<returns>Paremetre olarak gelen sayinin mutlak degeri.</returns>
            public static int MutlakDeger(int Deger)
            {
                  if(Deger < 0)
                        return -Deger;
                  else
                        return Deger;
            }
            /// <remarks>
            /// Kare Alma Islemi
            ///</remarks>
            ///<summary>
            /// Parametre olarak gelen sayinin
            /// karesini almak için kullanilir.
            ///</summary>
            ///<param name=”Deger”>Karesi alinacak sayi.</param>
            ///<returns>Parametre olarak gelen sayinin karesi.</returns>
            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 <summary>, <param name=”Deger”> ve <returns> etiketlerini otomatik oluÅŸturdu. <remarks> 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 <remarks> etiketi ile sınıf yada metod ile ilgili kısa bir açıklama yapılır. <summary> 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.
|
<c>
|
Açıklama içindeki bir bölümün “kod fontu” ÅŸeklinde olduÄŸunu vurgulmak için kullanılır.
Örnek :
/// <summary>
/// Bu sınıf <c>Stream</c> sınıfından türemiştir.
/// </summary>
public class YeniSınıf
{
    …
} |
|
<code>
|
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 :
/// <summary>
/// Bu metod iki Kompleks türeden sayıyı toplar. Örneğin
/// <code>
/// Kompleks sayi1 = new Kompleks(5,6);
/// Kompleks sayi2 = new Kompleks(0,1);
///
/// Kompleks sayi3 = sayi1 + sayi2;
/// </code>
/// </summary>
public Kompleks operator+(Kompleks sayi1, Kompleks sayi2)
{
    …
} |
|
<example>
|
Bir metodun yada sınıfın ne şekilde kullanılacağını açıklayan blok bu etiket içinde yazılır. <code> etiketinin kullanımı ile hemen hemen eşdeğerdedir. <code> etiketini verilen örneğin aynısı <example> etiketi içinde geçerli olduğu ayrıca bir örnek vermeye gerek yoktur.
|
|
<excepiton>
|
Bir metodun fırlatabileceÄŸi istisnai durumlarla ilgili bilgi vermek için kullanılır. <exception> 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 :
/// <summary>
/// Bu metod iki Kompleks türeden sayıyı toplar. Örneğin
/// </summary>
///
/// <exception cref=”IndexOutOfRange”>
/// </exception>
/// <exception cref=”OzelIstisnaiDurum”>
/// </exception>
public Kompleks operator+(Kompleks sayi1, Kompleks sayi2)
{
    …
} |
|
<list>
|
HTML kodlarındaki <li> etiketine benzer bir amacı vardır. Liste ÅŸeklinde bir yapı oluÅŸması gerektiÄŸi bildirilir. <listheader> listedeki baÅŸlık bilgisini, <item> listedeki her elemanı, <term> her elemandaki terimi ve <description> bu eleman hakkındaki detaylı bilgiyi bildirir. Â
Örnek :
/// <remarks>Bu bir liste örneğidir.
///
/// <list type=”number”>
///
/// <listheader>
/// Â Â Â Â <item>
/// Â Â Â Â Â Â Â Â <term>term 1</term>
///         <description>Açıklama 1</description>
/// Â Â Â Â </item>
/// </listheader>
///
/// <item>
/// Â Â Â Â <term>term 2</term>
///     <description>Açıklama 2</description>
/// </item>
///
/// <item>
/// Â Â Â Â <term>term 3</term>
///     <description>Açıklama 3</description>
/// </item>
///
/// </list>
/// </remarks>
public class YeniSınıf
{
    …
}
Not : Liste tipi(<list type=”number”>) “number” olabileceÄŸi gibi “bullet” ve “table” da olabilir.
Â
|
|
<para>
|
<summary> gibi uzun açıklama bloklarında bir paragrafı belirtmek için kullanılır.
Örnek :
/// <summary>
/// Bu sınıf Stream sınıfından türemiştir.
/// <para>
/// Bu sınıf aynı zamanda IDisposable arayüzünü uygulamıştır.
/// </para>
/// </summary>
public class YeniSınıf
{
    …
} |
|
<param>
|
Bir metodun parametreleri ile ilgili bilgi vermek için kullanılır.
Örnek :
///<param name=”Sayi1″>Toplanacak birinci sayı</param>
///<param name=”Sayi2″>Toplanacak ikinci sayı</param>
public static double Topla(int Sayi1, int Sayi2)
{
     return Sayi1 + Sayi2;
} |
|
<paramref>
|
<paramref> 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 :
/// <summary>
/// Bu sınıfın <paramref name=”Sayi1″/> , ve
/// <paramref name=”Sayi2″/> ve biçiminde iki parametresi vardır.
/// </summary>
public static double Topla(int Sayi1, int Sayi2)
{
     return Sayi1 + Sayi2;
} |
|
<permission>
|
Ü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 :
///<permission cref=”Private”>Herkes bu metoda eriÅŸebilir.
///</permission>
public static double Topla(int Sayi1, int Sayi2)
{
     return Sayi1 + Sayi2;
} |
|
<remarks>
|
Bir tür hakkında kısa bir açıklama vermek için kullanılır.
Örnek :
///<remarks>
/// Özel cebirsel işlemleri tanımlar.
///</remarks>
public class Cebir
{
   ….
} |
|
<returns>
|
Bir metodun geri dönüş değeri ilgili bilgi vermek için kullanılır.
Örnek :
/// <remarks>
/// Kare Alma Islemi
///</remarks>
///<summary>
/// Parametre olarak gelen sayinin
/// karesini almak için kullanilir.
///</summary>
///<param name=”Deger”>Karesi alinacak sayi.</param>
///<returns>Parametre olarak gelen sayinin karesi.</returns>
public static double KareAl(double Deger)
{
      return Deger * Deger;
} |
|
<see>
|
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 :
/// <summary>
/// Bu metod iki Kompleks türeden sayıyı toplar. Örneğin
/// </summary>
///
/// <see cref=”KompleksAlgoritmalar”/>
public Kompleks operator+(Kompleks sayi1, Kompleks sayi2)
{
    …
} |
|
<seealso>
|
Yazı içinde ilgili elemanla yakından ilişkili olan diğer elemanlara bağlantı vermek için kullanılır. Kullanımı <see> etiketi ile aynıdır.
Örnek :
/// <summary>
/// Bu metod iki Kompleks türeden sayıyı toplar. Örneğin
/// </summary>
///
/// <seealso cref=”operator-”/>
/// <seealso cref=”operator/”/>
/// <seealso cref=”operator*”/>
public Kompleks operator+(Kompleks sayi1, Kompleks sayi2)
{
    …
} |
|
<summary>
|
Üye elemanla ilgili geniş açıklama yazmak için kullanılan bir etikettir.
Örnek :
///<summary>
/// Cebir sinifi bazi özel matematiksel islemleri
/// yapmak için çesitli statik metotlar sunar.
///</summary>
public class Cebir
{
   …
} |
|
<value>
|
Sınıfın bir üye elemanı olan özellikler (Property) hakkında bilgi vermek için kullanılır.
Örnek :
///<value>
/// Kontrolün rengini belirtir.
///</value>
public int Renk
{
    get { return a;}
    set { a = value;}
} |
Kodlarınızı XML yorumları ile süslemiyi unutmayın !…
Yorumlar
Yorum Yok
Yorumunuzu Ekleyin
Yorum eklemek için giris yapmalısınız.