Temiz Kod: Yorumlar

Temiz kod pratiklerinde yeni konumuz yorumlar. Henüz okumadıysanız ilk pratiğimiz olan isimlendirme yazımızı okumanızı tavsiye ederiz. Çünkü ikisi birbirini tamamlar nitelikte.

Kendini iyi anlatan bir kodun yoruma ihtiyacı yoktur, çalışmalarımızı yürütürken hepimizin gönlünden geçen de budur. Ancak pratikte bu pek mümkün değildir. Kod teknik olarak ne kadar temiz olursa olsun, yaptığı işin veya algoritmanın karmaşıklığından dolayı yorumlar eklememiz gerekebilir. Geliştirmeyi yapan kişi koda hakim olabilir, fakat amacımız başkalarının da kodu anlayabilmesi ve gerektiğinde modife edebilmesidir. Yani bir nevi iletişim aracıdır.

Peki temiz yorum nasıl yazılır?

1) Yorum kodu değil, kodun yazılış sebebini anlatmalıdır. Farz edelim bir listemiz var ve biz bunu traverse ederken 1’den başlıyoruz. Halbuki bildiğimiz gibi bir çok dilde indeksler 0’dan başlar:

// Start traversing from 1.

for (int i = 1; i < parameters.length(); i++) {

      // codes

}

Buradaki yorum hiç bir anlam ifade etmeyecektir. Çünkü kodun tekrarı oluyor. Bunun yerine indeksin 1’den başlatılma sebebi belirtilmeliydi. Örneğin; “start traversing from 1 because the first parameter is a system parameter assigned automatically.”

2) Yorum yazmadan önce kodu bir gözden geçirin. Yorum yazmadan kod iyileştirilerek daha anlaşılır hale getirilebiliyorsa önce bu yola başvurun. Benzer şekilde yorum yazmakta zorlanıyorsanız, kodda bir sorun olma ihtimali vardır.

3) Kodda değişiklik yaptığınızda, mevcut yorumlar güncelliğini yitirmiş veya artık gereksiz(redundant) olabilir. O an bunu yapmazsanız, sizden sonraki geliştiricilerin kafası karışacaktır çünkü tutarsizlik  yaratacaktır. Üstteki örnekten devam edecek olursak; farzedelim refactor sonucu artık döngümüze ilk elemandan başlayabiliyoruz:

 

 // Start traversing from 1 because the first parameter is a system parameter assigned automatically.

for (int i = 0; i < parameters.length(); i++) {

      // codes

}

Bu durumda artık yorumu silmemiz gerekir.

4) Özellikle C++ gibi low-level dillerde, farklı dll’ler birbirlerinin metotlarını çağırabiliyor. Bu metotlarda bir değişiklik yapıldığında -özellikle metot ismi, parametreler gibi signature kısmı- veya drop edildiğinde, çağıran dll invalid durumuna düşebilir. Bu durumlar için metotun başına bağımlılıklarını(dependency) belirtmekte fayda var:

 

//—————————————————————————–

// Name: ConvertByteArraytoString

//

// Description:

// Converts byte array to null-termınated string

// The method is used by customermanagement.dll as well. Be careful when you move or remove the method.

//

// Parameters:

// pbValue – [in] byte array value

//

wchar_t* ConvertByteArraytoString(

BYTE *pbValue)

{

// codes

}

5) Kodunuzu bir yerlerden kopyaladıysanız veya referans aldıysanız linkini yorumlarına eklenemeniz faydalı olur.

Yazımızı Jeff Atwood’un Effective Programming: More Than Writing Code kitabındaki sözüyle noktalayalım:

---

Önceki yazı: Temiz Kod : Parametreler

---