Yazılım geliştirme günlüğü

.NET dilleriyle geliştirilmiş bir program sınıflardan oluşur. Sınıflar içinde de sınıf, yapı, numaralandırma, yordam gibi üyeler bulunur. İyi bir programcı, bu üyelerin kodlamasını önemsediği kadar üyelerle ilgili dokümantasyonu da önemsemelidir. Hem grup çalışmalarda bir başkasının sınıflar içindeki yapıların işlevini anlaması hem de geçmişe dönüp kodlarımızı incelediğimizde kod satırlarını daha rahat anlamak için kodlarımız arasına açıklamalar eklemeliyiz. Programlara hem tek satırlı hem de çok satırlı açıklamalar ekleyebiliriz. .NET dilleri dili açıklamalar için XML tabanlı belgelendirme formatı da sunar. Böylece hem standart bir biçim sağlanır hem de ihtiyaç duyulduğunda tüm açıklamalar XML olarak çıkarılarak msdn veya başka formatlarda etkili proje dokümantasyonu oluşturulabilir.
XML açıklamalar sınıf (class), değişken (variable), yordam (method), numaralandırma (enum), temsilci (delegate), olay (event), indisleyici (indexer) ve özellik (property) düzeyinde yapılabilir. XML açıklama, isim uzayı (namespace) için açıklama girmeyi desteklemez. Açıklama yapmak istediğimiz üyenin başına gelerek C#’ta “///” (üç tane slash) VB.NET’te ” ”’ ” (üç tane apostrof) işaretini yazdığımızda otomatik olarak o üyeye uygun XML yapısı eklenir. Bu yapı çeşitli etiketlerden oluşur. Bunların en önemlileri IntelliSense ve VS.NET “Object Browser” tarafından kullanılan <summary>, <param>, <remarks> ve <returns> etiketleridir

• <summary> etiketi, üye ile ilgili özet bilgi geçmek için kullanılır.
  
• <param> varsa o üye içinde kullanılan parametreleri temsil eder. Parametre sayısı kadar <param> etiketi kullanılır.
  
• <remarks> etiketi üye ile ilgili daha geniş bilgi girmek için kullanılır.
  
• <returns>, fonksiyonlarda kullanılarak fonksiyonun geriye döndürdüğü parametre hakkında bilgi verir.
  

Namespace ABCYazilim

    ''' 

    ''' Bu class, ABC Yazılımın Müşteri Hizmetleri ile ilgili tüm modüllerini içerir.
    ''' 
    Public Class MusteriHizmetleri

        ''' 

        ''' MusteriHizmetleri sınıfında kullanılan müşteri numarası.
        ''' 
        Private MusteriId As Integer

        ''' 

        ''' Müşteri Hizmetleri sıfının yapılandırıcısı.
        ''' 
        '''  Müşteri Hizmetleri sınıfının yapılandırıcı olup tek parameter alır. Sınıfı kullanıma hazırlar.
        '''
İşlemlerin uygulanacağı müşteri numarası 
        Sub New(ByVal MusteriId As Integer)
        End Sub

        ''' 

        '''Müşterinin borcunu döndürür.
        ''' 
        '''
Borçların alınacağı dönem.
        ''' Belli dönemdeki borcunu döndürür.
        Function GetBorc(ByVal Donem As String) As Integer
            Return 100
        End Function

    End Class

End Namespace

namespace ABCYazilim {
    /// 

    /// Bu class, ABC Yazılımın Müşteri Hizmetleri ile ilgili tüm modüllerini içerir.
    /// 
    public class MusteriHizmetleri
    {

        /// 

        /// MusteriHizmetleri sınıfında kullanılan müşteri numarası.
        /// 
        private int MusteriId;

        /// 

        /// Müşteri Hizmetleri sıfının yapılandırıcısı.
        /// 
        ///  Müşteri Hizmetleri sınıfının yapılandırıcı olup tek parameter alır. Sınıfı kullanıma hazırlar.
        ///
İşlemlerin uygulanacağı müşteri numarası 
        public MusteriHizmetleri(int MusteriId)
        {
        }

        /// 

        ///Müşterinin borcunu döndürür.
        /// 
        ///
Borçların alınacağı dönem.
        /// Belli dönemdeki borcunu döndürür.
        public int GetBorc(string Donem)
        {
            return 100;
        }//GetBorc

    }//MusteriHizmetleri

}//ABCYazilim

Bunlarla birlikte XML açıklamalar içinde kullanılabilecek diğer etiketler aşağıdaki tabloda verilmiştir:

Bu etiketleri örneğimizdeki GetBorc() yordamına uygulayalım.

'''
Müşterinin dönem borçlarını döndürür. 
'''
Borçların alınacağı dönem.
'''Belli dönemdeki borcunu döndürür.
'''Örneğin :
'''	
'''		MusteriHizmetleri o1 = new MusteriHizmetleri(45);
'''		nesne üretildi.()
'''		int Borc = o1.GetBorc("2006");
'''	
''' 
''' 
'''
 parametresi 2005 veya 2006'tan farklı girilirse.
'''	
''' Bu metodun doğru çalışması için:
'''

'''		
'''			Veritabanın hazır olması gerekir.
'''		
'''		
'''			Tabloda 2005 ve 2006 kayıtları olmalıdır.
'''		
'''	
''' 
Public Function GetBorc(ByVal Donem As String) As Integer
    If (Donem = "2005") OrElse (Donem = "2006") Then
        Throw New ArgumentOutOfRangeException("2005 veya 2006 giriniz.")
    Else
        Return 100
    End If
End Function

///
Müşterinin dönem borçlarını döndürür. 
///
Borçların alınacağı dönem.
///Belli dönemdeki borcunu döndürür.
///Örneğin :
///     
///         MusteriHizmetleri o1 = new MusteriHizmetleri(45);
///         ///nesne üretildi.()
///         int Borc = o1.GetBorc("2006");
///     
///
///
///
 parametresi 2005 veya 2006'tan farklı girilirse.
///
///Bu metodun doğru çalışması için:
///

///           
///               Veritabanın hazır olması gerekir.
///           
///           
///               Tabloda 2005 ve 2006 kayıtları olmalıdır.
///           
///       
///

public int GetBorc(string Donem)
{
    if ((Donem == "2005") || (Donem == "2006"))
        throw new ArgumentOutOfRangeException("2005 veya 2006 giriniz.");
    else
        return 100;
}//GetBorc

Peki, bu şekilde kodlarımızın arasına serpiştirdiğimiz açıklamaları nasıl belgelendirebiliriz. İnternet’ten bulabileceğimiz bazı araçlardan bu xml etiketlerini help dosyalarına çevirebiliriz. Bunun için tercih ettiğim araç NDoc programıydı. Özellikle açık kodlu olmasıyla ilgi çeken bu program ile msdn veya latex formatında çevrimiçi belge hazırlayabiliriz. Fakat Ndoc aracı sadece .NET 1.0 ve .NET 1.1 sürümlerini desteklemektedir. .NET 2.0 ile birlikte Ndoc (http://sourceforge.net/projects/ndoc/) geliştiricileri yeni sürüm üzerine çalışmayacaklarını ve projenin bittiğin ilan ettiler. .NET 2.0 için aşağıdaki araçlar kullanılabilir:

• Vsdocman VS.NET’le bütünleşik çalışır. (http://www.helixoft.com)
  
• Doxygen (http://www.stack.nl/~dimitri/doxygen/)
  
• Doc-O-Matic http://www.doc-o-matic.com

VS.NET üzerinden programımız içerisindeki açıklama etiketlerini bir xml dosyasına rahatlıkla çıkarabiliriz. Bunu yapmak için VS.NET’te bulunduğumuz projeyi sağ tıklayıp Properties bölümüne girelim.
C# tarafı için :
Gelen pencerenin sol tarafında Build bölümüne girerek xml dosyasının oluşmasını gerektiğini dosya adı girerek belirtebiliriz.

Aynı işlemi komut satırında da gerçekleştirebilirdik:
Csc OrnekBelge.cs /target:library /doc:OrnekBelge.xml

OrnekBelge.xml olarak belirlediğimiz dosya, derlemeden sonra programımızın bulunduğu klasörde oluşacaktır.

VB.NET tarafı için
Gelen pencerenin Compile bölümünde “Generate XML documentation file” seçeneğini işaretleyelim. Bu durumda VS.NET projeye ait projenin assembly’siyle aynı isimde bir .xml dosyası oluşturacaktır.

Aynı işlemi komut satırında da gerçekleştirebilirdik:
VBC OrnekBelge.vb /target:library /doc:OrnekBelge.xml

Fikir vermesi açısından NDoc’un eski uyarlaması üzerinden bu işlemi yapacağız. NDoc programını açıp programımızın .exe ve .xml dosyasını göstermemiz yeterli olacaktır. NDoc aracını kullanırken .xml dosya isminin assembly ile aynı olmasına dikkat etmeliyiz.

Dosyaların yolunu gösterdikten sonra “Build Documentation” butonu tıklarsak tüm ilgili dosyalar oluşacaktır. Son olarak, belirlediğimiz klasöre gidip index.html dosyasını çalıştırarak çalışmanın sonucunu görebiliriz.

Bu şekilde farklı araçlar kullanarak XML açıklamalarını HTML formata çevirebiliriz. Bu işlem esnasında bahsettiğimiz XML açıklama etiketleri aşağıdaki şekilde HTML etiketlerine dönüşür.