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ı: 1148

Yazılımda dokümantasyon devamlı konuşulan konulardandır. Nihayetinde dokümantasyon hararetli bir alandır, şiddetli taraftarlıklara konu olur ama muhtemelen en başarılı taraftarlık her zaman “dokümantasyon yapmamak”tır. Yani herkes bu konuyu farklı açılardan ele alır ama hala dokümantasyon yerinde sayar. Özellikle projelerin başında bu konuda belli kararlar alınsa ve uygulansa bile hararetin ilk arttığı dakikadan itibaren muhtemelen ilk terkedilen şey dokümantasyon olur.

Bu yazıda kodun dokümantasyonu üzerine bir şeyler yazmak istiyorum. Ama önce kod dokümantasyonundan ne anlıyoruz onu bir netleştirmemiş lazım. Kod dokümantasyonu öncelike ikiye ayrılır: Kodun API dokümantasyonu ve kodun iç dokümantasyonu. Bu yazıda ilkini ele alalım.

Kodun API dokümantasyonundan kastım, kodda var olan sınıf, arayüz, metot vb. yapıların “ne yaptıklarının” dokümantasyonudur. Buna kısaca arayüz dokümantasyonu (interface documentation) ya da daha bilinen haliyle API dokümantasyonu (API documentation) denir. API, malum Application Programming Interface’in kısaltmasıdır ve bir yazılımın sahip olduğu sınıf, arayüz, metot vb. yapıların dışarıdan görünene taraflarının tamamına denir. Dolayısıyla API’de kod yoktur, kodun tanımı vardır. API, bir yazılım sisteminin alt bileşenlerinin ne yaptığına odaklanır. Bu anlamda API kod değildir, kodun arayüzüdür ve “ne”liği vurgular, “nasıl”lık üzerine detay barındırmaz. Tam da bu yüzden kod dokümantasyonu derken, kodun içinde bulunduğu sınıf, metot vb. yapıların dokümantasyonu ile kodun içinde yapılan, iç dokümantasyonu ayırırız.

Kodu anlamak, doğrudan IDE üzerinde açılan kodlara bakarak elde edilemeyecek kadar karmaşık bir iştir. API kültürünün olmadığı yazılım ortamlarında yapılan, kodu IDE’de açıp, sınıflar ve metotlar arasında gezinerek, kodu takip ederek, gerekirse debugger kullanarak, kodun detaylarını anlamaya çalışmaktır. Bu ise iğneyle kuyu kazmaktan farksızdır ve çok yanlışa sebep olur. Kodu anlama, bir metot için örneğin, “bu nasıl çalışıyor?” sorusuyla başlamaz, “bu ne yapıyor” sorusuyla başlar. Ne yaptığını anlamadan nasıl yaptığına girişmek ya da nasıl yaptığını anlayarak ne yaptığını çıkarmak, metodolojik olarak zaten yanlış yöntemlerdir, çünkü detayda kaybolursunuz, bu yüzden de çok yorucudur ve aşırı zaman tüketmenize sebep olur. Kod ile ilgili çalışmalarımızın ezici tarafının var olan kodu değiştirmek olduğu gerçeğini düşünürseniz, kodun ne yaptığını anlamanın ne kadar önemli olduğunu farkedersiniz.

API dokümantasyonu sadece yazılım geliştirenler açısından değil, bir yazılımı dışarıya geliştirtenler açısından da hayati öneme sahiptir. Yani bir kurum dış bir kaynakla, kendisine yazılım sistemi geliştirmesi için anlaşıp,  sonrasında geliştirilen bu sistemi içeriye alıp BT biriminin sorumluluğuna vermeyi düşünüyorsa, projeyi geliştiren takımdan sadece kod değil, kodun beraberinde API dokümantasyonunu da alması gereklidir. Kodun geliştirilmesi için tonla para harcayıp, sonra heyula hale gelmiş kod tabanını hiç bir API dokümantasyonu olmadan içeriye alıp yazılımcıların önüne yığmak bence hayret verici derecede problemli ve cesur bir iştir. Bunu yapan yazılım yöneticilerini anlamadığım gibi bu duruma karşı bir eleştiride bulunmayan, aslında olup biteni kavramamış, bu yüzden de itiraz edemeyen yazılımcılara da hep hayretle bakmışımdır. (Gerçi, itiraz edilse ne değişir diyebilirsiniz ama ben daha çok “problem olmaz, kodu devralırız” diye cesurca ortaya çıkan yazılımcıları kastediyorum.) Prensip şu olmalı: Kod varsa APIsinin dokümantasyonu da olmalı. Bu durum geliştirenler açısından da geliştirtenler açısından da devir alanlar açısından da böyledir. Çünkü kod sadece çalışıyorsa, anlaşılamıyorsa, değiştirilmekte zorlanılıyorsa, kandırıldınız demektir. Çünkü kodun çalışması, zaten olmazsa olmaz özelliğidir. Satın almayı planladığınız bir aracın çalışmasından farklı değildir. Eğer aracınızın lastiklerini değiştirmek çok zor ve  2500 TL’ye mal oluyor ve daha da kötüsü her gün değiştirmek zorunda kalıyorsanız, aracın nasıl çalıştığıyla ilgilenmezsiniz. Durum bence yazılım açısından bu kadar vahimdir.

Bence aynı durum kurumundaki BT biriminde yazılım geliştiren ya da yazılım evleri için de geçerlidir, hatta daha vahimdir. Bu amaçla yazılım geliştiren ya da geliştirten her yer ve herkes kullandıkları teknolojide var olan API dokümantasyonu yapmak için gerekli yapıları öğrenmeli ve uygulamaya koymalıdır.

Kodun API dokümantasyonu noktasında Java severlerin kullanabileceği JavaDoc isimli nefis bir yapı ve araç var. JavaDoc, Java ile yazılan kodların API dokümantasyonunu yakmak üzere oluşturulmuş bir standart ve bir araç. JavaDoc’un nasıl yazılacağı ve üretileceği ile ilgili daha önce burada ve burada iki yazı yazmış ve örnek üzerinden de açıklamıştım. Artık hemen her dilde API dokümantasyonuna yönelik standartlar ve araçlar oluşturuluyor. Bu anlamda eskilerden daha şanslıyız, yeter ki gerekliliğine inanalım ve vakit ayıralım.

Bir sonraki yazıda kodun iç dokümantasyonunu ele almak üzere.

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