Kodlama Yönergeleri

 

Bu belge Cotonti geliştiricileri için temel öneri ve gereksinimleri içermektedir. Farklı alışkanlıklara ve anlayışlara sahip farklı kişilerin işbirliğinin sonucu olarak kaliteli ve sağlam bir ürün geliştirmelerine yardımcı olur.

#1. Önerilen Yazılım

Cotonti şu anda PHP 5.6 ve üstü ile çalışmasına rağmen, PHP 7.4 / 8.1 / 8.2'yi daha sağlam, katı ve modern olarak kullanmanızı öneririz. MySQL sürümleri için temel olarak 8.x'e güveniyoruz.

Not defteri yerine bazı IDE'leri veya özel Düzenlemeleri kullanmanızı şiddetle tavsiye ederiz, çünkü geliştiricinin zamanının% 30'undan tasarruf sağlar ve basit hatalardan kaçınmaya yardımcı olur. 

Dahası, Cotonti Kodlama Standartlarını kullanmak için yapılandırabilirsiniz.

 

Modern geliştirme yazılımlarının çoğu (hafif bile olsa) eklenti altyapısı sağlar ve birçok yararlı özelliği karşılayabilir: 

  • Uzak sunucu desteği ile sağlam proje ortamı.
  • Görev odaklı arayüz ile proje yönetimi. Sözdizimi vurgulama, gerçek zamanlı sözdizimi denetimi, otomatik tamamlama, kod ipuçları ve daha fazlası. 
  • Cotonti ana deposu veya kendi deponuzla verimli iş akışı için GIT gibi Sürüm kontrol sistemleri desteği. 
  • Emmet gibi hızlı kodlama araçlarıyla üretkenliği artırın. Yapılandırma belirli kodlama standartlarını korur. Yerleşik veya bir eklenti gibi. 
  • MySQL DB ile çalışabilme ve SQL dosyalarını düzenleyebilme/yönetebilme

 

Şimdi, bunlardan birini tavsiye edemeyiz, ancak bunları kontrol etmenizi ve kendiniz için en iyisini seçmenizi tavsiye edebiliriz:

#2. Kod Organizasyonu

#2.1. Fonksiyonlar

Bir kod yazdığınızda, bunun bir yerde yeniden kullanılıp kullanılamayacağını düşünün. Tüm yeniden kullanılabilir kodlar, kopyala ve yapıştır yaklaşımı yerine fonksiyonlar olarak çağrılabildiğinde daha iyidir. Bu nedenle, mümkün olduğunca yeniden kullanılabilir ve genel kod yazın. 

Fonksiyonlarınızı include dosyalarına koyun ve API dokümantasyonunu sağlayın, böylece diğerleri için bunların nasıl kullanılacağı açık olacaktır. Mantığı görünümden ayrı tutun. Örneğin, veritabanından bazı verileri almak, işlemek ve şablonda işlemek için işlevler sağlamak istiyorsanız, bir yerine 2 işleve sahip olmanız daha iyi olur: Birincisi, bazı değişkenlerde sonuçlanan verileri almak ve işlemek için ve ikincisi düzeni oluşturmak için. 

Her zaman çalışmaz, ancak çoğu durumda bunu takip etmeye çalışın. Kodunuza HTML ve doğal dil değişmezleri koymayın. Uluslararasılaştırma (dil dosyaları) ve kaynak dizeleri veya şablonların kendisini kullanın. İlk uyguladığınızda zaman alıcı olabilir, ancak değişiklikler söz konusu olduğunda çok tasarruf sağlayacaktır.

#2.2. Yorumlar ve dokümantasyon

Yorumlar ve açık bir API referansı, Kod Stil Kılavuzuna uymanın yanı sıra başkalarının kodunuzu anlaması ve kullanması için çok zaman kazandırır.

İyi kodun kendi kendini belgelediği yaygın bir ifadedir, ancak yine de durmadan devam eden yüzlerce satırda kaybolmamak için bazı yorumlara ihtiyaç vardır. Bu nedenle, kodunuzdaki mantıklı kısımları ve önemli adımları yorumlayın.

Bariz şeyleri açıklamayın, ancak örtük olan veya dış bağlama bağlı olan şeyleri açıklayın. Cotonti'de, üzerinde fazla zaman harcamadan kutudan iyi API dokümantasyonu elde etmek için PHPDoc tarzı yorumlar kullanıyoruz. 

Lütfen aşina olmak ve kodunuzda kullanmak için http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.quickstart.pkg.html adresini okuyun. NetBeans, Eclipse PDT, Zend IDE ve diğer bazı IDE'lerin phpDoc commenents için yerleşik desteğe sahip olduğunu unutmayın.

 

#3. Uygulama Gereksinimleri

Kod yazarken hatırlamanız gereken bazı temel noktalar şunlardır: 

Kodda kullanmadan önce değişkenleri içe aktarın ve filtreleyin. isset() ve empty() kontrollerini kullanın. 

Bir değişkenin gönderilip gönderilmediğini tespit etmek için is_null() işlevini kullanın.

    SQL sorgularında kullanmadan önce tüm değişkenlerin $db->quote()/$db->prep() ile filtrelendiğinden veya int olarak yazıldığından emin olun. 

Alternatif olarak, değişkenleri sorgulara gömmek için yer tutucuları kullanın. İçe aktarılan değişkenleri dosya adlarına dahil etmeyin. 

PHP'de register_globals kullanmayın, $_GET, $_POST ve $_COOKIE'yi açıkça kullanmayın. Girdi verisi filtreleme için Cotonti yerleşik fonksiyonu cot_import() kullanın. Doğrudan mysql_ çağrıları yerine SQL soyutlama katmanı kullanın.

Değişken enterpolasyonu gerektirmeyen dizgilerde çift tırnak yerine tek tırnak kullanın. SQL sorgularında tam sayıları 'tırnak' içine almayın.

Bu şekilde onlara sayısal yerine dize algoritmaları uygularsınız, bu da belirli sorgular için %10-40 performans kaybına neden olabilir.

#4. Github ile Geliştirme

Sürüm kontrolünü kullanırken hatırlamanız gereken birkaç şey:

Değişiklikler üzerinde çalışmaya başlamadan önce yerel kopyanızı güncelleyin (git pull), aksi takdirde değişikliklerinizi göndermeye çalışırken sorunlarla karşılaşabilirsiniz. 

Dikkatli olun. Değişikliklerinizi işlemeden önce test edin. Bu sizi çok fazla baş ağrısından kurtaracaktır. Sık sık işleyin.

Değişikliklerinizi küçük adımlarla, birden fazla işleme ayırarak işlemek daha iyidir. Her commit için açık bir yorum yazın, böylece herkes tam olarak ne yaptığınızı bilir. 

Commit komutu git commit -m 'Fixed #123 small bug concerning xyz' şeklindedir (bir sorun numarasına atıfta bulunun ve kısa bir açıklama ekleyin). 

Kararlı kilometre taşlarını etiketleyin. En azından, genel indirme için yayınlayacağınız her sürümün bir etiketi olmalıdır. 

Bir etiket oluşturmak için komut git tag -a v1.0 -m 'Version 1.0' (sürüm numarasını uygun şekilde değiştirin) şeklindedir. Bir etiketi Github'a göndermek için git push --tags komutunu kullanmalısınız.

 



1. Orkan  2008-08-16 05:08
yup, but dont get too excited with comments in code, like putting comments on every single line :p

IMO, good idea is to explain WHY, not what it does...
2. Trustmaster  2008-08-16 05:29
Agreed. A common practice.
3. dervan  2009-02-04 19:23
what is name of subdirectory for plugin text info (manual, examples, etc.)?
4. Trustmaster  2009-02-23 04:26
/plugins/plugin_name/doc
5. mahemall  2015-04-18 18:17

do you have architecture diagram for the frame work and refference guide. say for example if I want to quiery in database do I need to do it as regular php or is there any functions to get the results as array, same how about form validation ?

Yalnızca kayıtlı kullanıcılar yorum yapabilir