Açıklamalar niçin mi gereklidir? Bir programın kullanım ömründe çeşitli değişiklikler ve revizyonlar yapma gereken zamanlar vardır. İşte açıklamalar bu zamanlarda yapılması gereken değişiklikleri ve revizyonları kolaylıkla yapmak için, gereklidir. Açıklamalar sadece programda yapılacak sonraki değişiklikleri tespit veya programda kullanılan fonksiyonların hangi sürümlerinin kullanıldığını kolayca tespit amacıyla yazılmalıdır. İyi bir açıklama koda bakarak açıkça anlaşılamayacak şeyleri ifade etmelidir.
Açıklama Başlıkları
Açıklama başlıkları yazılmış kod üzerinde çalışırken programın içerisinde aranılan kod satırını bulmak bazen zor olduğundan dolayı, kodu ana gruplara ayırmak ve istenen bilgileri kolayca elde etmek amacıyla yazılır. Açıklama başlığı gelecekte kod üzerinde değişiklik yapmak isteyen programcıya aşağıdaki bilgileri sağlamalıdır:
- Programın başlığı ve amacı.
- Kodun geliştiricisi ve kodun yaratılma tarihi.
- Revizyon tarihçesi listesi.
Örnek:
;; Başlık: Bahçe yolu
;; Amaç: Arazi çizimleri için, bahçe yolu çizer
;; Geliştirici: S.T.
;; İlk yaratılma tarihi: 2-5-1998
;; Revizyonlar:
;; 10-9-1999 – Yay çizme hatası düzeltildi.
;; 15-9-1999 – Program çalıştırmadan önceki geçerli çizim modu kaydedildi ve program sonunda geri yüklendi.
Açıklamaları Hizalama
Bazı açıklamalar kodun gövdesinde olmalıdırlar; bunlar girinti düzeyi açıklamalar olarak adlandırılırlar. İsminden de anlaşılacağı gibi, girinti düzeyi açıklamaları tanımladıkları kod ile aynı girinti düzeyinde olmalıdırlar.
En iç girinti düzeyindeki açıklamalar fonksiyonun veya modülün özet tanımı olacaktır. Şayet fonksiyonu ve değişkenleri doğru olarak isimlendirdiyseniz, girinti düzeyi açıklamaları fonksiyon içerisinde yapmanıza gerek kalmayacaktır. Şayet bir açıklama yapmanın gerekli olduğunu hissederseniz, yapacağınız açıklama kodun NASIL yaptığından ziyade NİÇİN yaptığını açıklamalıdır. Açıklama kodun nasıl okunması gerektiğini açıkça belirtmelidir.
Şayet bir şeyleri çalıştırmak için, iyi bir programlama stili özelliğini ihlal ederseniz, kod üzerinde daha sonra çalışması muhtemel programcıların bu işlemi niçin bu şekilde yaptığınızı anlayabilmelerini sağlamak için, kodunuzun içerisine açıklamalar eklemelisiniz. Ayrıca açıklama kodun kendisini gerçekten açıklamaksızın sonraki programcılara ileteceğiniz bir not da olabilir.
Şayet çok karmaşıklarsa, kontrol yapılarını açıklamak isteyebilirsiniz; fakat kontrol yapılarını daha basit hale getirmek için, kontrol yapılarını tekrar yazmayı da tercih edebilirsiniz. Kodunuz daha iyi yapısal işlemlere ve isimlendirmelere sahip oldukça daha az açıklama yapmaya gerek duyarsınız.
Veri yapıları verileri nasıl ve niçin ayarladığınızı açıklamak için, açıklama yapmanın uygun olacağı yerlerden bir tanesidir.
Sayılar verilerin bulunduğu birim kısımları açıklamalar koymak için, iyi yerlerdir. Şayet programınız kullanıcının milimetre veya fit birimleri arasında seçim yapmasını bekleyecekse, bunu kodun ilgili kısmında açıklama olarak belirtmelisiniz. Ayrıca sayısal verilerin izin verilen sınırları da açıklanmalıdır. Böylece gelen verilerin kontrolü gerçekleştirilebilir.
Genel veri değişkenleri kodun içinde ne amaçla bulundukları belirtilmek suretiyle açıklanmalıdır. Şayet kodunuz içerisindeki genel değişkenlerinizi doğru şekilde isimlendirdiyseniz, bunlarla ilgili açıklama yapmanız gereksiz olabilir; fakat buna rağmen bu değişkenleri niçin genel değişken olarak tanımladığınızı açıklamalar yazarak belirtebilirsiniz.
Şayet bir fonksiyonu açıklıyorsanız, fonksiyonun girdileri ve çıktıları hakkında bilgi verdiğinize emin olun. Ayrıca fonksiyonun sürümü hakkında da bilgi verebilirsiniz. Şayet yazmış olduğunuz program yeterince kısa ise, kodun içerisine herhangi bir açıklama koymanız gereksiz olabilir. Şayet açıklama yapmak gerekli değilse, o açıklama yazılmamalıdır ilkesini unutmayın.
Sadece girinti düzeyi açıklamaları biçimlendirme “format” kuralına sahiptirler.
Aşağıdaki örnekte görüldüğü üzere, açıklamaları önlerine iki adet noktalı virgül (;;) işareti koyarak kodun bulunduğu o anki geçerli (aktif) girintiden yazmaya başlayın.
Örnek:
(defun P-ARRAY ( / n af yn cen c ra );; Dizideki eleman sayısını tanımlama(setq n 0)
Özet
Açıklamalar kod yazılırken yazılmalıdır. Açıklamaları yazmak için, kodun tamamlanmasını beklemek yanlış bir uygulamadır. Çünkü kodu yazarken kodun neresine bir açıklama koymanın gerekli olduğunu bilirsiniz. Fakat daha sonra emin olamayabilirsiniz.