Kod açıklama satırları denince hemen okul yılları aklıma geliyor . Hocalarımız üstüne basa basa kodumuza açıklama satırı yazmamız gerektiğini vurgulardı. Hatta ödevlerde,projelerde açıklama satırı olmayan kodlardan puan kırarlardı yanlış hatırlamıyorsam. Ayrıca yeni bir programlama dili öğrendiğimizde ilk olarak nasıl açıklama satırı koyarız onu öğrenirdik.
İlk zamanlar bunu neden yaptığımızı hiç sorgulamamıştım ama o açıklama satırları kodun okunuşunu,şeklini bozduğu için pek sevmezdim diyebilirim. Fakat yinede açıklama satırlarını bol bol kullanıp, kullanmayanları da uyarırdım.Peki neden kodumuza açıklama satırı koyma ihtiyacı duyuyoruz hiç düşündük mü?İlk başlarda gerekli olduğunu düşündüğüm için bunu hiç sorgulamamıştım fakat şimdi düşündüğümde o zamanlar koyduğum çoğu açıklama satırının şimdi gereksiz olduğunu anlıyorum. Peki neden gereksizdi? Çünkü o açıklama satırları okunulabilirliği,anlaşılabilirliği düşük olan kötü kodun kendim ya da başkaları tarafından anlaşılabilmesi için yazılmıştı. Kod okunduğu zaman ne yaptığını ifade edemiyordu bende bu yüzden açıklama satırları ile kodun ne yaptığını ifade etmeye çalışıyordum. Kodumuzun okunduğu zaman kolaylıkla anlaşılabildiğini düşünün o zaman bu kod için açıklama satırları yazmamıza gerek olurmu sizce? Bence olmaz çünkü kodun kendisi açıklama satırları gibi kendini ifade ediyor.Bu yüzden tekrar açıklama satırı koymaya gerek kalmayacaktır.
İş yerindeki çalışma arkadaşım bana Commentless Programming savunucusu diye bir ünvan takmıştı.Tabi bunun benim ortaya attığım bir fikir olmadığını söylemem gerekir. İlk olarak kod açıklama satırlarının bir kötü kod belirtisi olduğunu Martin Fowler’ın Refactoring Improving the Design of Existing Code kitabında okumuştum. Fowler kitabında benimde çok hoşuma giden “Kod açıklama satırları kötü kokan kodun fazla kokmasın diye üzerine sıkılmış deodorantlardır.” ifadesini kullanıyordu. Daha sonrada kendi deneyimlerimle çoğu yerde açıklama satırlarının gereksiz, çoğu zaman kötü yazılmış bir kodun belirtisi olduğunu gördüm.
Ufak tefek birkaç örnekle neden ve hangi durumlarda açıklama satırlarının gereksiz olduğunu anlatmaya çalışacağım.Bu örnekleri mümkün oldukça gerçek hayatta yazılmış kodlardan kesitler alıp göstereceğim. Öncelikle en fazla karşılaştığım açıklama satırlarından başlamak istedim.
Gereksiz açıklama satırları
public class MapObject{
Map mapData = null;
MapList mapList = null;
Vector mapJList = new Vector(4, 1);
/**
* Consructor, Creates a new instance of MapObject
*/
public MapObject() {
MapListLoader mapListLoader = new MapListLoader();
mapList = mapListLoader.loadMapList();
Logger.printDebugMessage("Maps loaded...");
mapJList = createMapJObjects(mapList);
}
}
class User {
private String address;
//..
/*
gets address
*/
public String getAddress() {
return address;
}
}
Şimdi yukarıdaki kodda gördüğünüz açıklama satırına bir bakalım.MapObject sınıfındaki Consructor’ının üzerine “Consructor, Creates a new instance of MapObject” yani anlamazsınız diye söylüyorum demiş yazan “bu bir yapıcı metod ve bu sınıfın yeni bir örneğini oluşturur.” 
Evet bunun zaten bir yapıcı metod olduğunu görebiliyoruz. Her Java, C# kullanıcısıda bunun böyle olduğunu açıklama satırını okumadan da anlayabilir.İkinci User sınıfımızda da javada zaten bir getter olan ayrıca gayet anlaşılır getAddress metodunun üzerine “Adresi getirir” açıklama satırı eklenmiş. Bunlara benzer açıklama satırları oldukça gereksizdir. Ekranda boşu boşuna yer kaplayıp diğer kodun okunmasını zorlaştırır.Bu tarz açıklama satırlarını hiç düşünmeden elimizden geldiğince hızlı sililiyoruz.
Değişkenler için kullanılan açıklama satırları
public class GetMapInfo{
private static String strMapDir = ""; // map physical path
private static String strMapServerURL = ""; // Map Connection URL
//.................
}
Yukarıda gördüğümüz açıklama satırlarıda düzgün isim verilmemiş değişkenleri ifade etmek için kullanılmış. Mesela ilk değişkenin ismi strMapDir açıkçası ben ilk gördüğümde harita klasörü gibi bişey anlıyorum fakat yanındaki yorum satırını okuyunca haritanın fiziksel yolunu ifade ettiğini anlıyorum.Diğer strMapServerURL değişkenine baktığımızda da yanına açıklama satırı yazma gereği duyulmuş çünkü değişkenin ismi tam olarak kendini ifade edemiyor bu yüzden açıklama satırlarından yardım alınmış. Şimdi bu değişkenleri düzgün isimlendirip açıklama satırlarını kaldırdığımızda aşağıdaki gibi olan kodumuza bakalım.
public class GetMapInfo{
private static String mapPhysicalPath = "";
private static String mapConnectionURL= "";
//.................
}
Şimdi yukarıdaki koda baktığımızda değişkenlerin isimleri ne olduklarını gayet iyi ifade ediyor.Gördüğünüz gibi değişkenleri düzgün isimlendirdikten sonra bu değişkenler için tekrar açıklama satırı yazmaya gerek kalmadı.
Metodlar ve parametreleri için kullanılan açıklama satırları
/**
* Builds LayerList object with Layer list
* @param list Layer list
* @return LayerList
*/
private LayerList loadLayerList(List list){
Layer layer = null;
LayerList layerList = new LayerList();
for(int i = 0; i<list.size(); i++){
layer = (Layer) list.get(i);
layerList.add(layer);
}
return layerList;
}
Yukarıda gördüğünüz metodun açıklama satırına bakacak olursak metodun ne yaptığını ve parametre olarak gelen list değişkeninin ne ifade ettiğini yazmış.Açıklama satırına bakacak olursak verilen Layer(katman) listesi ile bütün katmanların bilgilerini içinde barındıran LayerList nesnesi oluşturduğunu yazıyor buraya kadar güzel metodun ne yapmak istediğini anlıyoruz.Fakat metod ismine baktığımızda loadLayerList ben açıkçası “harita listesini yükle” anlıyorum.Açıklama satırlarını okumasam sanki bir veritabanından ya da başka biryerden LayerList nesnesini yükleyeceğini sanırdım ama öyle olmadığını açıklama satırı bana söylüyor.İkinci açıklama satırıda parametre olarak alınan list parametresinin bize Layer listesi olduğunu ifade ediyor fakat metoda baktığımızda (List list) gibi parametre aldığını görüyoruz açıklama satırlarını okumadan da bu list parametresinin Layer listesi olduğunu anlamamız çok zor.Buradaki problem düzgün verilmemiş metod ve paramatre isimlerinden kaynaklanıyor. Metod ismi metodun ne yaptığını ifade edemediği için,parametre ismide kendisini ifade edemediği için açıklama satırlarının yardımına başvurulmuş sorun geçici olarak çözülmüş. Fakat biz bu metodu ve aldığı parametreyi aşağıdaki gibi düzgün olarak isimlendirirsek açıklama satırlarına gerek kalmayacak.
<span style="color: blue">
private LayerList buildLayerList(List layerList){
Layer layer = null;
LayerList layerList = new LayerList();
for(int i = 0; i<list.size(); i++){
layer = (Layer) list.get(i);
layerList.add(layer);
}
return layerList;
}
Açıklama satırlarını silip metodumuzun ismini private LayerList buildLayerList(List layerList) olarak değiştirdik. Şuanda metodun adını okuduğumda bana direk olarak ne yaptığını ifade edebilir hale geldi adından da anlaşıldığı gibi buildLayerList yani LayerList nesnesi oluşturuyor.Parametre olarak alınan listeninde layerList olduğunu parametre adından kolaylıkla anlayabiliyorum. Gördüğünüz gibi düzgün isimlendirilmiş metod ve parametreler açıklama satırlarına gerek kalmayacak şekilde kodun okunulabilirdiğini arttırıyor.
Metodların içinde kullanılan açıklama satırları
private void Aktivasyon_Load(object sender, System.EventArgs e)
{
//Disk modelinin bilgilerini al
ManagementClass clsDiskSurucu = new ManagementClass("Win32_DiskDrive");
ManagementObjectCollection DiskSurucu = clsDiskSurucu.GetInstances();
ManagementObjectCollection.ManagementObjectEnumerator DiskSurucuEnumerator;
DiskSurucuEnumerator=DiskSurucu.GetEnumerator();
DiskSurucuEnumerator.MoveNext();
ManagementObject DSS = (ManagementObject)DiskSurucuEnumerator.Current;
string diskModel = DSS["Model"].ToString();
//BIOS seri numarasının bilgilerini al
ManagementClass clsBios = new ManagementClass("Win32_BIOS");
ManagementObjectCollection Bios = clsBios.GetInstances();
ManagementObjectCollection.ManagementObjectEnumerator BiosEnumerator;
BiosEnumerator=Bios.GetEnumerator();
BiosEnumerator.MoveNext();
ManagementObject BBios = (ManagementObject)BiosEnumerator.Current;
string biosSeriNumarasi = BBios["Caption"].ToString();
//Disk modeli ile BIOS seri no string olarak alınıyor ve şifre oluşturuluyor
sifre= biosSeriNumarasi + diskModel;
//Oluşturulan makina bağımlı string md5 ile hashleniyor
sifreHash = FormsAuthentication.HashPasswordForStoringInConfigFile(sifre, "md5");
//Oluşan hashli stringi alanlarına yerleştiriliyor
SKod1.Text = sifreHash.Substring(0, 3);
SKod2.Text = sifreHash.Substring(3, 3);
SKod3.Text = sifreHash.Substring(6, 3);
SKod4.Text = sifreHash.Substring(9, 3);
SKod5.Text = sifreHash.Substring(12, 3);
}
Yukarıda gördüğümüz bu küçük C# metodu içinde birçok açıklama satırı kullanılmış.Açıklama satırlarını okumadan anlayamıyorsunuz ama Metod kısaca aktivasyon işlemleri için bazı işlemler yapıyor.Yorum satırlarına baktığınızda önce diskin modelini alıyor ardından bios seri numarasını alıyor ardından bunları birleştirerek bazı alanlara yerleştiriyor. Bu tarz; içinde açıklama satırı bulunduran metodların problemi çok fazla iş yapmaları, aslında içlerinde birden fazla potansiyel metod barındırmalarıdır bunu da yorum satırlarından kolaylıkla anlayabilirsiniz. Burada yorum satırları mantıksal olarak ayrı olan üç ayrı işlemi ifade etmek için kullanılmış.Bunlar diskin modelini alma,bios seri numarasını alma ve bunları bazı alanlara yerleştirme.Bu tarz yorum satırları bize kodumuzun Refactoringe ihtiyacı olduğunun sinyalini verir.Kodumuzu tekrar düzenleyerek yorum satırlarını silip aşağıdaki gibi değiştiriyoruz.
private void Aktivasyon_Load(object sender, System.EventArgs e)
{
sifre=GetBiosSeriNumarasi()+GetDiskModel();
sifreHash=FormsAuthentication.HashPasswordForStoringInConfigFile(sifre,"md5");
HashVeriyiAlanlarinaYerlestir();
}
private void HashVeriyiAlanlarinaYerlestir()
{
SKod1.Text=sifreHash.Substring(0,3);
SKod2.Text=sifreHash.Substring(3,3);
SKod3.Text=sifreHash.Substring(6,3);
SKod4.Text=sifreHash.Substring(9,3);
SKod5.Text=sifreHash.Substring(12,3);
}
private static string GetBiosSeriNumarasi()
{
ManagementClass clsBios= new ManagementClass("Win32_BIOS");
ManagementObjectCollection Bios = clsBios.GetInstances();
ManagementObjectCollection.ManagementObjectEnumerator BiosEnumerator;
BiosEnumerator=Bios.GetEnumerator();
BiosEnumerator.MoveNext();
ManagementObject BBios =(ManagementObject)BiosEnumerator.Current;
return BBios["Caption"].ToString();
}
private static string GetDiskModel()
{
ManagementClass clsDiskSurucu= new ManagementClass("Win32_DiskDrive");
ManagementObjectCollection DiskSurucu = clsDiskSurucu.GetInstances();
ManagementObjectCollection.ManagementObjectEnumerator DiskSurucuEnumerator;
DiskSurucuEnumerator=DiskSurucu.GetEnumerator();
DiskSurucuEnumerator.MoveNext();
ManagementObject DSS = (ManagementObject)DiskSurucuEnumerator.Current;
return DSS["Model"].ToString();
}
Yeniden düzenlenmiş metodlarımıza bakacak olursanız açıklama satırlarına ihtiyaç duymadan kodu okuyarak ne yapıldığını rahatlıkla anlayabilirsiniz.En önemli avantajlarından biride uzun metodumuzu yorum satırlarına göre 3 ayrı metoda bölmemiz oldu.Ve bu yorum satırlarımız aslında yeni gelen bu 3 metodun adları oldu.Metodların adlarını okuduğumuzda gayet açık olduğu görülebilir.
Gördüğümüz gibi kod açıklama satırları çoğu zaman kötü yazılmış kodun belirtileridir.Bu açıklama satırlarını kodumuza düzgün isim vererek, küçük küçük mantıksal parçalara ayırarak vb. tekniklerle ortadan kaldırabiliriz.Bu yüzden açıklama satırlarına çoğu zaman kodun düzeltilmesi gerektiğini belirten fırsatlar olarak bakıyorum. Tabi hiç açıklama satırı yazmayacakmıyız tarzı bir soru aklınıza geliyor olabilir.Yazacağız ama sadece gerektiği durumlarda ve çoğu durumda gerekmeyecek buna inanabilirsiniz.Belki yazdığınız bir metodda kullandığınız algoritmanın neden kullanıldığını yada daha sonra okuyan için dikkate alması gereken açıklamalar yapabilirsiniz. Ama genellikle kodun ne yaptığını açıklama satırları ile değilde daha düzgün okunabilir temiz kod yazarak sağlamaya çalışın.
