Bu site emekli olmuştur. Arşiv amaçlı olarak BT AKADEMİ sponsorluğunda yayın hayatına devam etmektedir.




C#nedir?com
 
YAZAR HAKKINDA
Sefer Algan
Sefer Algan
http://www.seferalgan.com
İletişme geçmek için tıklayın.
71 Makalesi yayınlanmakta.
Yazar hakkında detaylı bilgi için tıklayın.
Yayınlanan diğer makaleleri için tıklayın.
İlgili etiketler:  C# / VC#/.NET Sefer Algan
 
YAZI HAKKINDA
Türü : Makale
Serbest Köşede C#nedir?com üyelerinin hazırladıkları yazılar yayınlanır. Bu yazılar editör incelemesine girmeden yayınlanır.
Seviyesi : Başlangıç
Kategori : C# / VC#/.NET
Yayınlanma Tarihi : 5.7.2003
Okunma Sayısı : 23055
Yorum Sayısı : 0     yorum yaz
Site İçi AramaSİTE İÇİ ARAMA
Üye Girişini AçÜye GİRİŞİ
Üye girişi için tıklayın.
Kullanıcı Adı
Şifre
 
Beni her zaman hatırla
Bir hafta boyunca kullanıcı bilgilerinizi kullanıcı çıkışı yapana kadar hatırlar. (Paylaşılan bilgisayarlarda önerilmez.)
 
Şifremi / Kullanıcı Adımı unuttum.
 
.net TV RSS Serbest KÖŞE (?)
Serbest Köşede C#nedir?com üyelerinin hazırladıkları yazılar yayınlanır. Bu yazılar editör incelemesine girmeden yayınlanır.
emre TAŞ
Silindi
emre TAŞ
yazının devamı >
emre TAŞ
silindi
emre TAŞ
yazının devamı >
emre TAŞ
silindi
emre TAŞ
yazının devamı >
emre TAŞ
silindi
emre TAŞ
yazının devamı >
emre TAŞ
silindi
emre TAŞ
yazının devamı >
Makale Gönder Bende Yazmak İstiyorum
.net TV RSSBlogroll
Turhal Temizer
Conda install environment.yml Package 10.8.2022
Turhal Temizer
Mac OS/X Removing CUDA 10.8.2022
  Diğer Herşey
Sponsorlar
BT Akademi
Medya Portakal
Video Hosting Sponsoru
Csharpnedir.com bir Ineta üyesidir
Uzman Abi
Her Yönüyle C# - Sefer Algan
Kaynak Kodunuzu XML ile Süsleyin
 
Kapat
Sayfayı Yazdır Sık Kullanılanlara Ekle Arkadaşıma Gönder MySpace Del.Ico.Us Digg Facebook Google Mixx Reddit StumbleUpon

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
    • Yazılan Yorumlar
    • Yorum Yaz
    Bu konu hakkında yayınlanan yorum bulunmamaktadır.
    "Yorum Yaz" tabını kullanarak sizde yorumlarınızı yazabilirsiniz.
    Yorum yazabilmek için üye girişi yapmalısınız. Üye girişi için tıklayın.
    Üye değilseniz Üyel Ol linkine tıklayarak üyeliğinizi hemen başlatabilirisniz.
     
    • Bu Konuda Son 10
    • 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