"kodlara bolca yorum yazalım" miti

7-8 sene önce, profesyonelliğe taze taze adım attığım zamanlarda birkaç (PHP) freelance işi aldıktan sonra her türk genci gibi kendi uygulama geliştirme çatımı yazmaya başlamıştım.

Neredeyse yazdığım kod kadar "yorum" yazmak gibi değişik bir takıntım vardı. Çünkü o şekilde daha güzel, daha profesyonel, daha bir roket bilimi gibi görünüyordu.

Yıllardır da "yazdığınız kodu anlatın" goygoyu sektörün içinde var. Hatta, stajyerlerin, işe yeni başlayanların aldığı yegane tavsiye; "kodlarına yorum yazmayı unutma, yoksa 6 ay sonra o kodu sen de anlamazsın!" goygoyudur.

Halbuki, pratikte ideal bir yazılım geliştirme sürecinde, kod tabanında mümkün olduğunca az yorum olmalıdır.

Sürdürülebilir ve bakımı yapılabilir kod, kendi kendini anlatmalıdır. Kötü programlama teknikleriyle bir implementasyon yapıp, daha sonra o implementasyonu kodtaki satır sayısı kadar anlatmanın bir mantığı yoktur.

Bir kod parçasının ne yaptığını ayrı bir şekilde anlatmak için yorum satırlarına ihtiyaç duymamalıyız. Yazılan kod, gerek isimlendirme, gerekse modern yazılım kuralları dahilinde, zaten kendi kendini anlatacak seviyede basit ve açık olmalıdır.

Ama gerçek dünyada, bu işi %100 yapabilmeniz zor. Bazen elimizde olmayan sebeplerden, bazen tembelliğimizden bu basitliği kaybediyoruz ve neyi niye yaptığımızı anlatmamız gerekebiliyor. hatta, yalan söylemeyelim, işyerlerimizde genelde "workaround" ve "quick hack" modelleriyle günü idare ediyoruz. :)

gereksizin gereksizi yorumlar

meyveler = ["Elma", "Armut", ]
# listeye Ayva ekle.
meyveler.append("Ayva")

Aferin. Laf söyledi balkabağı. Python'ın listeleri dünyanın en temiz API'sine sahip olduğu halde, bizim küçük wozniak python standart kütüphanesi içerisindeki veri tipini dökümente etmek istemiş.

Buradaki tek sorun bu da değil; yarın birgün meyveler listesine Ayvayla birlikte "Cilek" eklemek istek, kodu düzenlemenin yanında bir de üstündeki gereksiz yorumu güncel tutmaya çalışacağız.

phpdoc ve benzeri araçlar

"Kaynak kod üzerinden dökümantasyon çıkaralım" fikri ilk kimden çıktı bilmiyorum ama bu arkadaşlar kaynak kod kalabalığı yapmaktan başka bir tek şekilli HTML çıktıları almaya işe yarıyor olabilirler.

Dahası, koda yeni geliştirmeler yaptığınızda bakımını yapmanız gereken bir de docstring'ler olacak. ve tembellikten orayı güncellemeyeceğiz. (güncellemiyoruz da) bu sefer, zaten açıkta olan bir bilgiyi, yorumlar bize yanlış iletecek. dahası, sevgili IDE'lerimiz o docstringleri okuyup, bize yanlış type bildirimleri yapacaklar.

Bir fonksiyonun aldığı her parametre için dökümantasyona ihtiyacımız yok. fonksiyonun, parametrelerin isimlendirmesine dikkat etmek, parametre sayısını abartmamak gibi işler yaptığımızda zaten yine bu stringlere ihtiyacımız olmayacak.

bir versiyon kontrol sistemi olarak kod dosyaları

Bu tip bir kullanım umarım 2015 senesi itibariyle kalmamıştır, ama güzel bir anı olarak kalsın;

Çok uzun yıllar önce (belki 9-10 yıl?) ceviz.net'in ceviz.net olduğu zamanlarda site yazılımında her bir değişiklik yapıldığında değişikliği yapan kodun başına, tarih, değişen kısım, değiştiren kişi şeklinde not düşüyordu.

"""
* "zaa" hatasi duzeltildi. "zort" durumunu da dusunmekte fayda var. - emre, 21.12.2007

* emre'nin bozdugu yerleri duzelttim. - ansugo, 20.12.2006

* hicbirinizin anlamadigi bir seyler yaptim. -acemi, 19.12.2005
"""

Bir dosya üzerinde 15-20 iş yapıldığını düşünün. :)