Evet Software Tech
Published in

Evet Software Tech

Kaynak Kod Dokümantasyonu’na Dair

Son günlerdeki gündemim kaynak kod dokümantasyonu nedir? Her konuda olduğu gibi burada da farklı farklı (desenler) yaklaşımlar söz konusu mu? Temiz kod yazmak dokümantasyona girer mi? gibi sorular dönüp duruyor kafamın içinde.

Klasiklerden olan Structure and Interpretation of Computer Programs”, 1985 kitabının önsözünde geçen;

“Programlar insanların okuması için ve sadece tesadüfen makinelerde çalışması için yazılmalıdır.”

Yine Donald E. Knuth, Literate Programming”, 1984 tarihli makalesinde benzer bir vurguyla;

“Programların inşasına yönelik geleneksel tutumumuzu değiştirelim. Asıl görevimizin bir bilgisayara ne yapması gerektiğini söylemek olduğunu düşünmek yerine bir bilgisayarın ne yapmasını istediğimizi insanlara açıklamaya odaklanalım.”

Bugün arayacağımız cevaplar konusunda kafamızda bir şeyler oluşturduğumuza göre haydi başlayalım.

Bir kaynak kod bizlere işin nasılını anlatır. Yorumlar ise nedenini.

Yorumlar üzerinden başlayacak olursak öncelikle “En iyi yorum ihtiyacımız olmayan yorumdur.” cümlesini açıklayalım.

Bahsi geçen yorumları çocukların bisiklet ile ilk tanıştıkları zaman dengede durmalarını sağlayan o küçük denge tekerlekleri gibi düşünebiliriz. Kodlarımızı o kadar basit hale getirmeliyiz ki bu denge tekerleklerine ihtiyacımız kalmasın.

Nasıl yani kaynak kodlarımıza yorum eklemeyecek miyiz? Cevabımız tabi ki HAYIR! Her satırı ne anlama geliyor. Ne yapıyor diye anlatmaya çalışırken ipin ucunu kaybedip kodumuzu iyice karmaşıklaştırıp kirletebiliriz. Bu sebepten ötürü her satırı adım adım yorumlamaktansa iş mantığının karmaşıklaştığı gerçekten açıklamaya ihtiyaç duyulan noktalara yorumlar eklemek iyi bir tercih olabilir.

Daha fazla yorumun daha okunabilir kod anlamına gelmediğini unutmayalım.

Yukarıda basit kod parçacığını incelediğimiz zaman dahi farkedeceğimiz yorumlar kodu daha karmaşık hale getirmeye meyilli olduklarını görebiliyoruz.

Yorum yazma ihtiyacını ortadan kaldırmak için kodu yeniden düzenlemek ve basitleştirmek için neredeyse sonsuz fırsatlarımız bulunsa da kendimizi sadece kod ile anlatmanın sınırlarının olduğu da aşikar bir durum.

Kodumuz her ne kadar basit ve anlaşılır olursa olsun. Kodun tamamen kendi kendini belgelemesi imkansızdır.

Kod programın neden yazıldığını şu ya da bu sebeple yöntemin alternatifler arasından neden seçildiğini açıklayamaz.

Bir geliştirici için bir kod mükemmel şekilde şeffaf olabiliyorken aynı kod bir başka geliştirici için aynı oranda opak olabilir.

Yukarıdaki kod satırının ne iş yaptığını çok iyi biliyor olabilirsin. Fakat bir önceki cümlemiz özelinde bu her geliştirici için mümkün olmayabilir. O zaman ufak bir geliştirme yapalım.

Yinelemek gerekirse aslında çok da zor değil aslında kod size programın nasıl çalıştığını söyleyebilir. Yorumlar ise ne işe yaradığını söyleyecektir.

Kaynak koda yorum eklemek en temelde geliştiricinin kullanmayı veya kullanmamayı kendisinin tercih edebileceği bir araçtır.

https://www.youtube.com/watch?v=ZsHMHukIlJY&t=395s

Yorumlar içeren bir kod için çok iyi kod diyemeyeceğimiz gibi; yorum içermeyen bir kod için de kötü kod diyemeyiz.

Bu kadar basit bir kod parçasını dahi anlamak için kısa da olsa bir zaman kaybı yaşayacağızdır. Haydi o zaman daha iyi hale getirelim.

Belirli noktalarda geliştirmeler yaparak kodumuzu daha anlaşılır bir hale geldiğini görebiliyoruz. IDElerin gücünü de göz ardı etmememiz gerekir tabi.

Yorumlar kaynak kodun bir parçasıdır ve kod ile sıkı sıkıya bağlıdır. İlgili kodumuzda bir değişiklik yapıldığı durumda yorumu da değiştirmeli hatta belirli durumlarda kaldırmak gerekebilir.

Koddaki değişikliğe rağmen açıklamaların değiştirilmediğini düşünün. Bu durum büyük iş mantıklarının olduğu kısımlar için fazlasıyla kafa karıştırıcı hatta yanıltıcı olabilir.

Teknik olarak yazılımın çalıştığı bilgisayar özelinde bu yorumlar önemsiz ve herhangi bir dezavantaj yaratmıyor olabilir. Fakat yazımızın başlarında da bahsettiğimiz üzere yazdığımız kodun asıl amacının bir insan için şeffaf olması konusunda hemfikiriz diye düşünüyorum.

Bu sebepten ötürü isimlendirmelerimizi, yorumlarımızı anlamlı bir bütün oluşturacak şekilde hazırlamalıyız.

Bu argümanlar üzerinde anlaştığımıza göre yorumları kullanmanın maliyetlerine ufak bir göz atalım.

  • Yorumların bakıma ihtiyacı vardır. Kod üzerinde bir geliştirme yapıldığı durumlarda açıklamaların da elden geçirilmesi bütünlük açısında çok önemlidir.

Modern yazılım projelerinde değişiklik olmaması büyük bir lükstür.

  • İyi açıklamalar yazmak zordur. İyi bir açıklama kesin ve konuyla net şekilde alakalı olmalıdır.
  • Geliştiriciler açısından açıklamalar ekleme konusunda yapılacak bir zorlama/dayatma geliştiricinin temiz ve anlaşılır kod yazmaktan uzaklaşmasına sebebiyet verebilir.

İlgili dokümanlarımızın iki temel muhatabı vardır.

  • Geliştiriciler için oluşturulan dokümanlar için iki temel soruya cevap aranır. Bu sorular “Kod ne işe yarıyor?” ve “Kod nasıl çalışıyor?”.

Geliştiriciler için önemli olan konuysa yukarıdaki iki maddemiz üzerinden kodun ne yaptığı ve nasıl çalıştığının açıklanması önemlidir.

  • Harici kullanıcılar içinse cevap aranan soru ise “Kod nasıl kullanılıyor?”

Harici kullanıcılar için genel olarak ilgili dokümantasyon kodun nasıl kullanılacağını açıklar. Bu nedenle API’lerin dokümantasyonu oldukça yaygındır.

Projelerin temelde

belgelerine sahip olması beklenir. Aynı zamanda tüm bu belgelerin güncelliği ve bütünlüğü yüksek derecede önem arz etmektedir.

Uzun vadede iyi bir koddan aşırı dokümantasyondan uzak ve kendini açıklıyor olması beklenir.

Böylelikle kaynak kod dokümantasyonu konusuna genel bir bakış yapmış olduk.

Kendinize çok iyi bakın.

--

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Mustafa Dikyar

Mustafa Dikyar

Software Developer

More from Medium

Just a simple Makefile to avoid to repeat yourself

Applying test-driven development to your database

Publish to NuGet with GitHub actions

How Mature Architecture Happens