Anlaşılır Kod
Anlaşılır kodun iki şartı vardır:
- Şekil şartı, standart olması
- İçerik şartı, odaklı olması (bir yerde sadece bir işin yapılması)
Standart
Anlaşılır kod öncelikle standarttır.
Mimariye Uyum: Belirlenen mimariye uygun geliştirilir.
İsim: Anlaşılır isimler içerir.
Şekil: Ferahtır, mekanı etkin kullanır dolayısıyla rahat okunur.
Şekil ve Dilin Kullanımı: Tutarlıdır, şaşırtmaz, beklenildiği gibidir, aşina olunandır.
Dökümantasyon: Gerektiği kadar, anlaşılmaya yardım edecek şekilde dokümante edilmiştir.
A- Mimariye Uyum
Mimari, üst düzey tasarımdır. Projede yol gözterici en temel şeydir. Temelde riskler ve fonksiyonel olmayan ihtiyaçlar göz önüne alınarak tasarlanır. Anlaşılırlık mimaride başlar. Mimari tasarım, takım üyelerince benimsenir, nasıl uygulanacağı öğrenilir ve projede uygulanır. Sonradan eklenen takım üyesinin entegrasyon maliyetini azaltır. Yeterli miktarda mimari tasarım, projenin başlarında belirlenir ve ihtiyaç oldukça yolda tamamlanır. Mimariye uyum şaşrtmayan bir kod yapısı ortaya koyar. Anlaşılır kod mimaride belirlenmiş yapıların dışına çıkmaz. Gerekirse mimari güncellenir ama daima mimariye sadık kalınır.
Robert C. Marin’e göre mimari tasarımın ana gayesi, yazılım sistemini geliştirmek ve bakımını yapmak için gerekli olan insan kaynağını en az seviyede tutmaktır.
Tasarım kalitesi ise, sistemi geliştirmek, bakımını yapmak, gerekli olan iş ve enerji ile orantılıdır. iyi tasarımlar, işi ve enerjiyi en az seviyede tutarlar, kötü tasarımlar ise daha çok iş ve daha yüksek enerjiye ihtiyaç duyarlar.
Kötü tasarlanmış mimari ile çalışmada çözüm, kısa yollar bularak mimariden sapmak değildir, mimariyi değiştirmektir. Aksi taktirde kötü mimariyi daha da kötü hale getirmiş oluruz. Nedeni ise iyi veya kötü, anlaşılmış olana uymaktır. Anlaşılma yönünden kötü bir çözüm bir çözüm, birden çok çözümden daha iyidir.
B- İsimlendirme
Phil Karlton
Bilgisayar Bilimlerinde sadece iki tane zor şey vardır: ön belleği temizleme ve şeyleri isimlendirme.
Temiz kodda, isimler de temizdir. Aksi halde kodun da temiz olması mümkün değildir. İsimler, düşünce dünyamızı ortaya çıkartırlar, ilkel ve karışık düşüncelerde, en temelde isimler belirsizdir.
Öncelikle, İngilizce isimler kullanılır. Programanın dili ingilizcedir. İngilizce isimlendirme ile, ilerideki yabancılarla çalışma, yazılımın kaynak kodunun satılması, açık kaynak kod yapılması gibi durumlarda problem yaşatmaz. ingilizce isimlendirme, söz dizimi ve yazım açısından da programlamaya daha uygundur.
Anlaşılır isimlendirmenin en temel engeli kısaltmadır. Her kısaltma bir kodlamadır. Mevcut psikoloji içerisindeki parametrelerden etkilenip isim verilmemelidir.
Çok bilindik, evrenselleşmiş değil ise kısaltmalardan kaçınılmalıdır. for döngüsünde kullanılan i,j,k gibi kısaltmalar evrenselleşmiş kısaltmalara örnektir. Evrensel kısaltmalar; http, tcp, pi v.b gibi. init() v.b fonksiyon/metot isimleri gibi. Bağlamdan anlamı hemen idrak edilebilen; in, out, r(circle’da yarıçap, radius) v.b değişken isimleri gibi.
Kısa ve anlaması zor isimler yerine uzun ve gerekirse okuması zaman alan ancak anlamlı isimlerin verilmesi daha iyidir.
Değişkenin aldığı değerlere bakark değişken isimleri verilmemelidir. km yerine distance olmalı gibi. Burada km’yi değil mesafeyi tutuyoruz. Değişkenlere isim verirken değişkenlerin neyi temsil ettiğini düşünerek vermeliyiz. Verilen ismim gerek metot gerekse değişkenin anlam ve amacını en iyi şekilde belirtiyor olması ve genel geçiyor olmaması gerekmektedir.
Ne yaptıpı bilinmiyorsa iyi isimde verilemez. Bunun yanında daima genel isimlerler verilmez ve daha özel, daha açıklayıcı olmalıdır isimler.
Tipler, değişkenler ve metotlar farklı kipte ve soyutlama seviyesinde isimler verilir. Tiplere, kavramı temsil eden, ismin yalın halinde isim verilir. Fonksiyonlar/metotlar, kavramın sorumluluğunu temsil eden emir kipinde isim alırlar. Değişkenler ise kavramın bir parçasını, özelliğini temsil eden yalın tipte isimler ile tanımlanır. Tip isimleri metotları, metot isimleri ise içindeki değişkenleri kapsamamlıdır. Bu amaçla iş alanı iyi anlaşılmalı ve teknik terimler kavranmalıdır.
Aynı kavramlara, işlere farklı yerlerde farklı isimler verilmemelidir. İngilizce ve Türkçe’yi karıştırarak isimlendirme yapılmamalıdır.
Metin(text, string) yada sayılsal v.b sabitlerde yanlış yazımların v.s önüne geçmek için enumeration v.b yapıları kullanılmalıdır. Bu şekilde hem daha yüksek şfade gücü elde edilir hem de type-safety kazanılır.
type-safety (Tip güvenliği): Programlama dilindeki veri tipi hatalarına karşı duyarlılığı ifade eden bir terimdir. Tür güvenliği, derleyicinin derleme sırasında türleri doğrulayacak ve değişkenlere atanan farklı tipteki türler içinde hata verecektir. Bundan dolayı ise type-safety dillerde değişken tanımlanırken türü de belirtilir.
Projeler için ortaklaşa belirlenen ve herkes tarafından benimsenen isim standartları oluşturulmalıdır.
Kısa kod iyidir ancak kısa kod kısa isimlerle sağlanmaz. Anlaşılma pahasına kısa kod yazılamaz. Anlaşılır olma ile kısa olma zaman zaman çelişebilir. Bu durumda aslolan anlaşılırlıktır. Kısa olmak adına anlaşılır olmaktan fedakarlıkta bulunulmamalıdır.
C-Standartlara Uyum
Muhakkak isimlendirme ve şekil (format) standatlarımız olmalıdır.
- Her dil için ayrı ayrı
- Veri tabanı için
- XML, properties dosyaları, web servisleri v.s için
Ve bu standartlara uyum kabul edilebilir kodun olmazsa omaz bir özelliği olmalı.
Kod kalite araçları, pair programing ve özden geçirmeler yardımıyla standartların uyulup uyulmadığı kontrol edilebilir.
Dilde kabul görmüş kodi geleneğe (code conventon) uyulmalıdır.
- CamelCase or camelCase
- snake_case
- kabab-case
Ayrıca özellikle değişken isimlerine ön ek getirerek (inNumberOfPeople) daha anlaşılır isimler amacıyla Hungarian gösterimi (notation) de vardır.
D-Dilin Kullanımı
- Kullanılan dilin olabildiğince herkesçe kabul görmüş şekilde, etkin (effective) ve standart yapılarla kullanılması, anlaşılırlığı arttırır.
- Aynı problemi farklı şeklde kodlayarak çözen kod parçaları, anlaşılma problemine sebep olurlar.
- Dillerde, uzun süren gelişim sürecinde aynı problemi çözmek için çok farklı deyimler geliştirilir.
- Bu deyimleri seçmek ve onlara uymak, standart kod yazmak açısından önemlidir.
- Her dilin, “idiom” denen ekndine has deyimleri ya da kalıpları vardır.
Idiom: Anlam olarak, dilin kurallarına uymak anlamına gelir. Bilginizi farklı bir dilden aktarmak yerine, bir görevi tamamlamanın en kolay ve en yaygın yollarını bulmaktır.
Örnek:
Bir nesne döndürmesi beklenen bir metodun nesne döndürmemesi durumu nasıl tasarlanmalıdır?
- null döndürüp, çağıran kodun null kontrolü yapmasıyla mı?
- Sıradışı durum fırlatarak mı?
- Optional v.b farklı dillerdeki çözümlerle mi?
Çözüm uygularken herkesin benimsediği bir yöntem kullanılmalıdır. Aynı problemin farklı çözüm şekillerinin kullanılması karmaşıklığa neden olacaktır.
Bu kapsamda Tasarım kalıpları ve Framework’ler dilin kullanımı açısından oldukça önemlidir.
Tasarım Kalıpları
- Tasarım kalıpları da (design patterns), dillerden bağımsız, sık tekrarlanan problemlere genel çözümler sunarlar.
- Nesne yaratmak ya da durumlu bir nesnenin hayat döngüsünü yönetmek gibi.
- Tasarım kalıpları zengin bir nesne rol kataloğu kazandırır.
- Tasarım kalıplarını yaygın bir şekilde kullanmak, dili daha etkin kullanmanızı, daha standart ve kaliteli koda bihayetinde de temiz koda sahip olmanızı sağlar.
Çerçeveler (Framework)
- Çerçeveler de (frameworks) kullandıklaı yapılar ve kalıplar ile kodların olabildiğince standart olmasını sağlarlar.
- Çerçeve kullanıldığında, onun yaklaşımlarına ve kullanımlarına uyulmalıdır.
E-Dökümantasyon
- Anlaşılır kodun son şartı, gerektiği kadar dokümanta edilmiş (commented-documented) olmasıdır.
- Anlaşılır kod için iyi isimlendirme ve odaklı olmaktan kaynaklanan kısalık yeterli değilse, kod açıklanmalıdır.
- Kodu açıklamak, kod dökümantasyonu (code documentation) ile olur.
Dökümantasyon gerekli mi?
Akın Kaldıroğlu
Eğer bir kodun anlaşılması için dökümantasyona ihtiyaç duyuluyorsa, bunun çözümü öncelikle dökümantasyon değildir.
Koda yazılan her yorum satırı bir özgür olduğu söylenir; anlaşılmaz ve kötü bir kod yazdım, anlamanız için yorumu da okumanız gerekli! Dolayısıyla kodunuza yorum yazarak onu anlaşılır hale getirmeyin, kodunuzu iyileştirerek (refactoring) anlaşılır hale getirin. Koda yazılın her yorumun bir özür olduğu söylenir. Bunun dışında gerçekten yorum satırı kullanılması gereken durumlar olabilir.
- Eğer bir sınıfın ya da değişkenin neyi soyutladığı, neyi temsil ettiği, bir metodun ne yaptığı v.s isminden anlaşılmıyorsa, öncelikle refactoring ile iyi isim verilerek anlaşılır hale getirilmelidir.
- Örneğin sınıfı bölüp, parçalamak, metot sayısını azaltmak v.s sınıfın anlaşılırlığını arttırır ve dokümantastyon ihtiyacını azaltır.
- Buna rağmen hala anlaşılma problemi olacaksa kısaca ne işe yaradıığ ve nasıl kullanıldığı açıklanabilir.
- Benzer şekilde, eğer bir metodun ne yaptığı, arayüzünden, yani isminden, geçilen parametrelerden, dönüş tipi ve fırlattığı sıra dışı durumlardan anlaşılmıyorsa, önce iyileştirme denenmelidir.
- Metodu bölüp, parçalamak en temel iyileştirmedir çünki belki de metot çok iş yapıyordur ve isim vermek zordur,
- Parametre sayısını, içindeki karar mekanizmalarını azaltmak v.s
- Buna rağmen halen anlaşımamı problemi olacaksa kısaca ne işe yaradığı açıklanabilir ve parametreleri, dönüş tipi ile fırlattığıa sıra dışı durumlar açıklanabilir.
Kod Dökümantasyonu
Kod ddökümantasyonunun iki türünden bahsedilebilir:
- Kod içi dökümantasyon, ihtiyaca bağlı olarak kısa “//” ya da “/* */” notları halinde yapılabilir.
- API dökümantasyonu, kodun arayüzünün dokümantasyonudur.
API dokümantasyonu çok daha önemli ve stratejiktir. Debugger kullanmaya hardcanan vakir API dokümantasyonuna harcamak çok daha faydalıdır.
- Kod içi yorumlar daha çok karmaşık algoritmalarda geçen yerel değişkenleri, bazı adımları, kontroller, beklenen ve beklenmeyen durumları, hesapları v.s daha anlaşılır kılmak için yapılabilir.
- Kod içi dokümantasyon, açık olanı, görüneni değil, iyi isimlendirmeye rağmen görünmeyeni, açık olmayanı açıklamalıdır.
- İkinci tür kod dokümantasyonu, API dokümantasyonudur.
- Kodun anlaşılmasından kasıt öncelikle API’nin anlaşılmasıdır.
- API dokümantasyonu sınıf/arayüz ve metotlar için yapılır.
- Metotların parametreleri, varsa dönüş değeri ve fırlattığı sıra dışı durumlar açıklanmalıdır.
- Özel formatı ve araçları vardır.
C#’da API dokümantasyonu, sınıf ve üyeleri için formatta yazılan açıklamalarla yapılır.
Documenting your code with XML comments: https://learn.microsoft.com/en-us/dotnet/csharp/codedoc
