Sandcastle

Genelde her yazılımcı kendi kodunu sıfırdan kendi yazmak ister ve sarı renkli debugging çizgisini yazdığı satırların üzerinde gezdirdikçe yazılımcının aldığı haz devamlı artar. Hele bir de hata çıkmadığı zaman kendi kod satırlarımız tadından yenmez. Fakat yeri geldiğinde ihtiyacımız olan kodu yazacak vaktimiz olmayabilir veya uzman olmadığımız bir alan üzerinde üzerimize bir iş atanabilir. Bu gibi durumlarda hazır yazılmış kütüphanelere başvurmak kaçınılmaz son olmaktadır. Burada bahsettiğim MS Enterprise Library olabileceği gibi mail sunucusuyla bize iletişimi sağlayacak olan MailBee.Net gibi yazılması spesifik bir alanda tecrübe gerektiren bir kütüphane de olabilir.

Amma velakin gün gelir kütüphane kullanan değil de kütüphane yazan yazılımcı olabilirsiniz ve bu görevi üstlenmiş bir yazılımcı olduğunuzda bazı sorumluluklar da Demokles’in kılıcı gibi kafanızın üzerinde devamlı sallanıyor olacaktır. Bu sorumluluklardan bazıları da kodun anlaşılabilirliği ve dokümantasyonudur.

Kodun anlaşılabilirliği için ilk yapmanız gereken -aslında her daim yapmanız gereken- semantik isimlendirme standartlarıdır. Konumuz bu olmadığından biz diğer yapmamız gereken dokümantasyona hızlıca geçelim.

Microsofta standartlarına göre en önemli dokümantasyon kod dokümantasyonudur. Yani metod, sınıf vs.lerin başlarına eklenen yorum satırları yazılımcıları bilgilendiren en önemli etmendir. Visual Studio ile hızlıca bu satırları eklemek için üç adet ‘/’ atmanız yeterlidir.

public static class Islemler
{
     /// <summary>
     /// İki sayıyı çarpabilirsiniz
     /// </summary>
     /// <param name="birinci"></param>
     /// <param name="ikinci"></param>
     /// <returns></returns>
     public static int Carp(int birinci, int ikinci)
     {
          return birinci * ikinci;
     }
}

Sandcastle

Şimdi ise asıl konumuz olan Sandcastle aracına yavaştan değinmeye başlayalım. Sandcastle, İngilizce mottosu “Documentation Compiler for Managed Class Libraries” olan Microsoft’un geliştirdiği doküman oluşturma aracıdır. Temel amacı tüm kütüphaneyi derleyip kodların üzerindeki yorum satırlarımızdan bize bir yardım dokümanı oluşturmaktır.

Sandcastle ile yardımcı dokümanları oluşturabilmemiz için öncelikle bazı kurulumlar yapmamız gerekmektedir. Bunlar sırayla;

• 1. Sandcastle
• 2. Sandcastle Help File Builder
• 3. Microsoft HTML Help

Bu kurulumları yaptıktan sonra Başlat menüsünden “Sandcastle Help File Builder > Sandcastle Help File Builder GUI” exe dosyasını çalıştırabilirsiniz. Uygulama açıldığında karşımıza çıkan ekranda “File > New Project” menüsüne tıkladığımız vakit doküman üretmemizi sağlayacak proje oluşturma ekranını görüyor olacağız.

Burada yapmamız sağdaki menüden bir doküman kaynağı eklemek. Bu doküman kaynağı aslında bir XML dosyasıdır ve class library, build edilme esnasında otomatikman bu dosyayı da oluşturmktadır (tabi ki ayarları yapıldığı vakit). Dolayısıyla ilk başta yapmamız gereken VisualStudio üzerinde kütüphanemizin “Properties” penceresini açıp burada “Build” sekmesindeki “XML documentation file” seçeneğini işaretlemek olacaktır. Proje build edildiğinde dosya yolunun gösterdiği yerde XML dosyasını bulabilirsiniz.

Daha sonrasında yapmamız gereken tekrar Sandcastle projemizin olduğu yere gelip oluşturduğumuz XML dosyasını ve projemizin dll’ini “Documentation Sources > Add Documentation Source” menüsüne tıklayarak eklemek olacaktır. Ayrıca yardımcı referanslar gerekiyorsa bunları da “References”a eklemeyi unutmayınız.

Artık tek yapmamız gereken “Documentation > Build Project” menüsüne tıklamaktır. Bundan sonrasını Sandcastle Help Generator hallediyor olacak. Sandcastle oluşturmayı tamamladıktan sonra bizim yapmamız gereken ise Sandcastle projesini kaydettiğiniz yerdeki Help klasörünün içinde Documentation.chm dosyasını bulup okumaya başlamak olacaktır.

Örnek dokümanı indir…

Daha kaliteli dokümanlar oluşturabilmek için Sandcastle aracında Properties penceresinde bazı önemli ayarlar bulunmaktadır. Bunlar;

• HelpFileFormat: Dokümanın çıktısının türünü değiştirebilirsiniz. Buradan yapabileceğiniz ayarlar;
  • HtmlHelp1 (chm)
  • MsHelp2 (Kullanım dışı, bunun yerine MsHelpViewer kullanılmalıdır)
  • MsHelpViewer (MSDN)
  • Website (ASP.NET MSDN)
• Keep Log File: Build output çıktısıyla log dosyası oluşturur, gerekmediği taktirde kapatılabilir.
• NamespaceSummaries: Dokümanda olmasını istemediğiniz isimalanlarını buradan işaretleyebilirsiniz.
• HelpTitle: Yardım dokümanı başlığı.
• HtmlHelpName: Dosya adı.

Sandcastle aracı temel anlamda kullanılması basit bir araçtır. Burada önemli olan zaten kod dokümantasyonunun baştan sıkı tutulmasıdır. Bir diğer yandan Build penceresinde “XML documentation file” seçildiği vakit Visual Studio Build ettikten sora bize düzgün dokümante edilmeyen kodları uyarı olarak gösterecektir. Bir başka yöntem olarak da StyleCop aracını kurup burada doküman validasyonunu açabilirsiniz. Bu uyarılar size dokümantasyonu düzelttireceği gibi encapsulation tercihlerinizi de gözden geçirmenizi sağlayacaktır.

Son olarak Sandcastle hakkında daha detaylı bilgi almak isterseniz aşağıdaki adresleri de ziyaret edebilirsiniz;

• http://www.sandcastledocs.com/
• http://blogs.msdn.com/b/sandcastle/