CSD-OS İşletim Sistemi Projesi - Fonksiyon Açıklama Standardı C ve Sistem Programcıları Derneği Kasım 2002
İçindekiler: 1 -GIRIŞ 3 1.1.NEDEN STANDARTLARA IHTIYACIMIZ VAR? 3 2 -İMLA VE YAZIM 3 2.1.TÜRKÇE AÇIKLAMALARDA 3 2.2.İNGILIZCE AÇIKLAMALARDA 3 3 -AÇIKLAMA DÜZENI 4 3.1.PROTOTIP 4 3.2.PARAMETRELER 4 3.3.BILDIRIM DOSYALARI 5 3.4.AÇIKLAMA 5 3.5.GERI DÖNÜŞ DEĞERI 5 3.6.KAYNAK KOD 6 3.7.DIĞER BILGILER 6 3.8.YAZAR(LAR) 6 3.9.NOTLAR 6 2
1 - Giriş Bu makale CSD İşletim istemi Geliştirme Projesi kapsamında proje grupları tarafından kullanılacak olan fonksiyon açıklama standardını tanımlamaktadır. Makale Nihan ÜNLÜTÜRKLER tarafından derlenmiştir. Makale ile ilgili sorularınız ve yorumlarınız için yazara nihan.unluturkler@csdos.org adresinden ulaşabilirsiniz. 1.1. Standarlara Neden Gereksinim Duyarız?! Fonksiyonların herkes tarafından doğru bir biçimde anlaşılması ve kullanılması gerekir. Pek çok fonksiyonun çeşitli parametre değerleri için özel davranışları vardır. Bu özel davranışlar eksiksiz bir biçimde ele alınıp dökümante edilmelidir.! Fonksiyonlar yalnızca yazan kişi tarafından kullanılmazlar. Kaldı ki fonksiyonu yazan kişiler bile bir süre sonra fonksiyonun nasıl kullanıldığını unutabilirler. Kullanılan fonksiyonlar hakkında açıklamaların kalıcı bir biçimde yapılması gerekir.! Ekip çalışmalarında ortak dil kullanılmalıdır. Standartlar bu ortak dili oluşturmaktadır.! Standartlar grup çalışmalarında zaman kazancı sağlar. 2 - İmla ve Yazım 2.1. Türkçe Açıklamalarda Dökümantasyonun yapıldığı ya da taşındığı elektronik ortam Türkçe karakterlerin problemsiz görüntülenmesini sağlayamıyorsa Türkçe de bulunup İngilizce de bulunmayan karakterler için onların en yakın İngilizce karşılıkları tercih edilmelidir. Türkçe karakterlerin en yakın İngilizce karşılıkları aşağıda belirtilmiştir: İ, ı Ş, Ç, Ğ; ş, ç, ğ Ö, Ü; ö, ü I, i S, C, G; s, c, g O, U; o, u yerine gelmelidir Şekil 1 Türkçe-İngilizce karakter dönüştürmesi 2.2. İngilizce Açıklamalarda İngilizce açıklamalarda oluşabilecek yazım hataları yazım denetim programları ile kontrol edilip düzeltilmelidir. Düzeltme işlemleri için Çeviri Grubu ndan yardım alınabilir. 3
3 - Açıklama Düzeni Açıklama düzeni sırasıyla Prototip, Parametreler, Bildirim Dosyaları ve Açıklama bölümlerinden oluşmaktadır. 3.1. Prototip Fonksiyon açıklama işleminin ilk bölümünü prototip bildirimi oluşturmaktadır. Bu bölümde açıklanacak fonksiyonun prototipi iyi isimlendirilmiş parametre değişkenleri kullanılarak yapılmalıdır. Parametre değişkenleri hakkında açıklamalar Parametreler bölümünde burada kullanılan isimler eşliğinde yapılacaktır. Fonksiyon prototipi kodlamada kullanılan prototip ile tamamen aynı olmalıdır. Kodlama ile dökümantasyon arasında hiçbir farklılığın olmaması esastır. PVOID AllocMem(HHEAP hheap, DWORD dwsize, DWORD dwflags); 3.2. Parametreler Fonksiyon parametreleri hakkında açıklamaları içerir. Burada her parametre değişkeni aşağıdaki yapıya uygun olarak işlevsel bakımdan açıklanmalıdır: Parametre değişkeni: Açıklama Açıklama tüm özel durumları kapsamalıdır. hheap: Tahsisatın yapılacağı heap sisteminin handle değeridir. Heap alanının handle değeri CreateHeap fonksiyonundan elde edilebilir. Bu parametre NULL olarak geçilirse tahsisat process in varsayılan heap alanı üzerinde yapılır. dwsize: Tahsis edilecek alanın byte cinsinden miktarını belirtir. Bu değer kullanıcı alanı için ayrılmış olan 3 GB değerinden büyük olamaz. dwflags: Tahsis edilecek alana ilişkin ek özellikleri belirler. Bu parametre aşağıdaki sembolik sabitlerle belirlenir. Birden fazla özelliği etkin hale getirebilmek için bu sembolik sabitler bit düzeyinde Veye işlemiyle birleştirilebilirler. HEAP_ZERO_MEMORY: Tahsis edilen bellek bölgesi sıfırlanır HEAP_NO_SERIALIZE: Tahsis edilecek bellek alanına birden fazla thread tarafından erişildiği durumda işlemler normal olarak iç içe girmeyecek biçimde seri hale getirilmektedir. Bu seçenek seri hale getirme işlemini kaldırmaktadır. 4
3.3. Geri Dönüş Değeri Bu bölümde fonksiyonun geri dönüş değerinin ne anlam ifade ettiğine ilişkin açıklamalar yer alır. Geri dönüş değerine ilişkin açıklamalar tüm özel durumları içerecek biçimde yapılmalıdır. Fonksiyon başarı durumunda tahsis edilen bellek bölgesinin başlangıç adresine, başarısızlık durumunda ise NULL değerine geri dönmektedir. Başarısızlığın en önemli nedenleri fonksiyonun birinci parametresine yanlış bir handle değerinin geçilmesidir. Başarısızlık durumunda başarısızlığın nedeni GetLastError fonksiyonu ile elde edilebilir. GetLastError fonksiyonunun bildireceği başarısızlık değerleri şunlar olabilir: ERROR_INVALID_HANDLE ERROR_NOT_ENOUGH_MEMORY 3.4. Bildirim Dosyaları Burada fonksiyon prototipinin bulunduğu başlık dosyası ile fonksiyonun kullanımı için gerekli olabilecek başlık dosyalarının hangileri olduğu belirtilir. Bazı fonksiyonların kullanılması için fonksiyon prototipinin yanı sıra bazı sembolik sabitler ve tür isimlerine de gereksinim duyulur. Başlık dosyalarının listelenmesi işleminde prototipin bulunduğu dosya en yukarıya yazılmalıdır. Hangi dosyasının hangi nedenle include edildiği belirtilmelidir. #include heap.h #include syserr.h heap.h syserr.h : Fonksiyon prototipi ve üçüncü parametre bulunan sembolik sabitler : Hata kodlarına ilişkin sembolik sabitler 3.5. Açıklama Bu bölümde aşağıdaki durumlar açıkça belirtilmelidir:! Fonksiyonun ne amaçla kullanıldığı! İşlevi! Çalışmasına yönelik özel ve istisna durumları Kullanım durumunda dikkat edilmesi gereken durumlar Bu fonksiyon process in önceden yaratılmış olan heap alanı üzerinde tahsisat yapmakta kullanılır. Tahsisat işlemi sistem tarafından seri hale getirilerek yapılmaktadır. Bu durum 5
farklı thread lerin kullanıldığı uygulamalarda heap organizasyonunun bozulmasına engel olur. Seri hale getirme işlemi fonksiyonun dwflags parametresinde HEAP_NO_SERIALIZE belirlemesi ile kaldırılabilir. Fonksiyon tahsis edilmek istenen alan boş heap alanından büyük ise başarısızlıkla geri döner. Boş heap alanının büyüklüğü GetHeapFreeSize fonksiyonu ile elde edilebilir. 3.6. Tanımlama Yeri Fonksiyonun hangi kaynak dosyada tanımlandığı burada belirtilmelidir. 3.7. Diğer Bilgiler Fonksiyonla ilgilii öğrenilmesi gereken başka dosyalar varsa, onlardan oluşan kısa bir isim dizisi Diger Bilgiler başlığı altında yazılmalıdır. 3.8. Yazarlar Kodun yazılış tarihi ve kim tarafından yazıldığı burada belirtilmelidir. Eğer kod üzerinde sonradan değişiklik yapılırsa; kim tarafından yapıldığı, tarihi ve yapılan değişikliğe ilişkin küçük bir not eklenmesi gerekmektedir. 3.9. Notlar Diğer bilgiler, kodu yazanın ve düzenleyenin yorumları, böcekler vs. burada belirtilmelidir. 6