Kod Dokümantasyonu – II: İç Dokümantasyon

Bir önceki yazıda kod dokümantasyonu ele aldık ve bu konunun iki alt başlığı olduğunu söyleyip kodun APIsinin dokümante edilmesinin ne anlama geldiğinden ve gerekliliğinden bahsettik. Dolayısıyla kod dokümantasyonundan bahsettiğimizde doğrudan kodun içine yazılan ve genellikle “iç dokümantasyon” (internal documentation) olarak adlandırılan ve Java vb. dillerde çoğunlukla “//” ile “comment” haline getirilen açıklama ifadelerini anlamamalıyız. API dokümantasyonu, kodu anlaşılır kılmak için yapılacak en önemli açıklamadır.

Öte taraftan, iç dokümantasyona geldiğimizde bunun API dokümantasyonu kısmından daha karmaşık olduğunu söyleyebiliriz. Sık sık duyuyorum, “hocam koda ne kadar dokümantasyon yazmalıyız?” şeklinde sorular. Hoş, bunu soranlar belli ki henüz öğrenci olan arkadaşlar ve kariyerlerinde hiç kod dokümantasyonu yazmama ihtimalinin yüksek olduğunu bilmiyorlar tabi 🙁

Açıkçası koda iç dokümantasyon yani açıklama (comment) yazmak, prensip olarak iyidir. İnsanların niyet olarak kodlarını anlaşılır kılmak için “dokümantasyon yapayım” diye düşünmeleri son derece güzel bir şeydir. Lakin kodu anlaşılır kılmanın, dokümantasyon yazmaktan daha önce gelen bir yolu vardır: kodu anlaşılır yazmak. Kodu karmaşık yazıp, özensiz, çala-kalem yazıp, sonra dokümantasyon ile anlaşılır kılmak, kötü kodu açıklamalar yoluyla tamir etmeye çalışmaktır. Bir inşaat ustası olarak duvarı üflesen yıkılacak şekilde kötü örüp sonra çok iyi bir sıva ile bütün bu durumu kapatmak gibi. (Biliyorum iyi bir örnek olmadı, sıvasız duvar olmaz ama dokümantasyonsuz kod olur 🙂  ) Ya da kendini ifade etmekte devamlı zorluk yaşayan, dili düzgün kullanamayan birisinin, düşüncelerini anlatmak için devamlı açıklamalar yapmasına benzer bu durum, konuştuka anlaşılmaz hale gelir. Bu yüzden aslolan dokümantasyon yazmak değildir, aslolan anlaşılır kod yazmaktır öyle ki açıklamaya gerek kalmasın. Buna “self-descriptive” ya da “self-documenting” kod da denir.

Eski kitaplarda örneğin 70lerin ve 80lerin kitaplarında kod ile dokümantasyonu arasındaki oranın 1/2 olmasından bahsedilirdi. Bir satır koda iki satır dokümantasyon! Bu açıkçası o zamanki ortamların ve dillerin yapısıyla, sahip olunan kültürden kaynaklanan bir durumdu. Örneğin bellek problemi çok kısa isimler vermeye zorluyordu yazılımcıları. Ama artık öyle değil, Allah’ın mekanı geniş, istediğiniz kadar uzun isimler yazabilirisiniz yeter ki anlamlı olsun.

Eğer kodunuzun yazdığınız haliyle anlaşılmasının zor olduğunu düşünüyorsanız, lütfen ona dokümantasyon yazmayın. Dokümantasyonu kodunu yazdığınız işin tabiatından kaynaklanan, örneğin karmaşık bir algoritmada olduğu gibi, anlama zorlukları için yazın. Ya da beklenenin dışında bir durum söz konusudur onu belirtin. “Ama hocam yaptığımız iş karmaşık ve kodu uzun tutuyor” diyorsanız, karmaşıklığı ile ilgili “bu durum olabilecek en basit hal midir? Daha da basitleştirilemez mi?”, uzun tutması için de “bir kez daha düşünün” bu kadar uzun olmalı mı? “Uzun olan işi atomik alt parçalara böldünüz mü?” diye sorarım. Dolayısıyla eğer kodunuzun yazdığınız haliyle anlaşılmasının zor olduğunu düşünüyorsanız, onu refactor edin, elden geçirin ya da tekrar yazın. İsimlerinizi kontrol edin, satırlarınızı atomik, tek bir işi yapacak hale getirin, zincirleme kod çağrılarını (a.f().g().u() gibi) açın, bol yerel değişken kullanın, metotlarınızın içinde atomik olan kısımları “{}” ile bloklayın ki o kısmı yalıtın ve nihayetinde kodunuzu bölüp parçalayın. Daha önce yazmıştım, kod eklenerek değil çıkartılarak büyür. Kodu anlaşılır kılmanın en temel iki yolu, iyi isimlendirme ve kısa kod yazmadır. Bunlara dikkat ederseniz, muhtemelen yazmak zorunda kalacağınız açıklamalar çok azalacaktır.

Bu konuda Brian W. Kernighan ve  P. J. Plaugher’ın “Don’t comment bad code—rewrite it.” yani “Kötü kodu açıklama – tekrar yaz.” şeklindeki sözlerini hatırlamak gerekir.

Uncle Bob’a atfedilen “Her açıklama bir özürdür.” sözü bakın şöyle bir cümlede geçiyor:

“A comment is an apology for not choosing a more clear name, or a more reasonable set of parameters, or for the failure to use explanatory variables and explanatory functions. Apologies for making the code unmaintainable, apologies for not using well-known algorithms, apologies for writing ‘clever’ code, apologies for not having a good version control system, apologies for not having finished the job of writing the code, or for leaving vulnerabilities or flaws in the code, apologies for hand-optimizing C code in ugly ways…”

Yani

“Her açıklama, daha açık bir isim ya da daha makul bir parametre seti seçilmediği ya da daha açıklayıcı değişkenler ve fonksiyonlar kullanılmadığı için bir özürdür. Kodu bakım yapılamaz kıldığı için özür, iyi bilinen algoritmalar kullanmadığı için özür, “zekice” kod yazdığı için özür, iyi bir versiyon yönetim sistemi kullanmadığı için özür, kod yazma işini bitirmediği için özür ya da kodda sıkıntılı veya hatalı kısımlar için özür, elle ve çirkin şekilde yapılmış optimize C kodu için özür… “

Peki hiç mi iç dokümantasyon yapılmamalı? Tabi ki hayır. Ben her halükarda API dokümantasyonunun yapılması gerektiğini düşünüyorum. Metot istendiği kadar basit olsun, bir cümleyle de olsa API açıklaması konmalı ki örneğin JavaDoc ile API dokümantasyonu ürettiğimizde her şey eksiksiz olsun.

Öte taraftan gerek API gerek ise kod içi dokümantasyonun kaçınılmaz olduğu durumlardan birisi ise devralınmış koddur. Devralınmış ve kötü ve karmaşık yazılmış koda değişiklik yaparken anladığınızı koda gerek API gerek ise içerideki satırlar düzeyinde açıklama olarak yazmanız o kodu gittikçe çok daha anlaşılır hale getirecek, takımdaki bilgi birikimini paylaşarak hızlandıracaktır. Ben, dışarıda geliştirildikten sonra içerideki geliştirme takımının önüne konan koda, devralan takımdaki yazılımcıların, dokundukları her noktaya anladıklarını kaydetmemelerini de anlamış değilim. Böyle hallerde herkes her yeri kendisince tekrar tekrar anlamaya çalışıyor demektir.

Uzun lafın kısası, açıklamaya yazma, açık kod yaz, kendini açıkça ifade eden kod yaz. Bu anlamda koduna bol bol açıklama yazandan ziyade, temiz ve açık kod yazan taktir edilir.

Koda yazılacak API ya da iç dokümantasyon için Robert Martin ya da Uncle Bob’ın “Clean Code“, P. Goodliffe’nin “Code Craft” ve Steve McConnell’in “Code Complete” kitaplarının ilgili kısımlarını okumanızı tavsiye ederim.

Açıklama gerektirmeyen, açık ve seçik kod yazmak ve devralmak ümidiyle 🙂

Toplam görüntülenme sayısı: 1149