Paper 11

Generated: Sat Oct 29 16:40:09 2005

prev (10) overview next (12)

11 - TitlePEAR Kodlama Standartları (PHP)
AuthorsSinan Yalçınkaya, Umut Işık, php.org.tr
PC MemberNo
Contact personSinan Yalçınkay, sinanyalcinkaya@gmail.com, 05553675508
Main Fields17. Ozgur yazilim, acik kaynak, edevlet ve e-turkiye
Other Main Fields
Abstract + KeywordsPEAR
( http://pear.php.net )

PROBLEM

        Yazılan kodların belirli bir standarta uygun yazılmaması kod okunurluluğunu azaltarak kodların
daha fazla hata bulundurması, yorumlanmasını zorlaştırması ve başka programcılar tarafından anlaşılamaması
gibi belli başlı zorlukları beraberinde getirmektedir.

        Gelişme standartların doğru belirlenmesi ve belirlenen standartlara uyulması ile mümkündür.
Hayatımızda pek çok standarta uymak zorundayız. Örneğin kullandığımız her türlü elektrikli eşya 220 Woltluk
bir güç akımı ile çalışmaktadır bununla birlikte kullandığımız fiş ve soketler standart bir yapıya sahiptir.
Eğer böyle bir standarta sahip bir yapı kullanılmasaydı hayatımızın ne kadar zorlaşacağını tahmin ediniz.

        PEAR Standartları açıklama satırlarının yazılması ve girintilerin belirli bir standartta yazılarak
yazılan kodların okunabilirliğini bu standarta uyan herkes için artırarak PEAR sınıflarının programcılar
tarafından ortaklaşa geliştirilip yaygın olarak kullanılmasını sağlamaktadır.

AMAÇ

        Bu çalışmada katılımcılara kodlama standartlarının önemi anlatılmaya çalışılarak PEAR kodlama
standartları ayrıntılı olarak açıklanacaktır.

SINIRLILIKLAR

        Bu çalışma PHP programlama dili ile program geliştirenlerle sınırlıdır.

        PEAR kodlama standartları PEAR için açık kaynaklı program yazımıyla sınırlıdır. Başka projeler için
program geliştirenlerin bu standartlara uyması zorunlu değildir.


PEAR standartlarında kod yazımı size aşağıdaki faydaları sağlayacaktır.

1. Yazdığınız kodun okunurluğunu artıracaktır.
2. Aynı standarta uyan kişilerin yazdıkları kodu daha çabuk anlayabileceksiniz (tabi onlar da sizinkileri) Dolayısıyla ekip çalışmalarında ve açık kaynaklı proje geliştirmede büyük fayda sağlayacaktır.
3. Yazdığınız bir programı üzerinden zaman geçtikten sonra dahi daha kolay anlayabileceksiniz.
4. Yazdığınız programlar daha az sorun ile çalışacak ve zamandan kazanacaksınız.
5. Açıklamalarınızın belli bir standarta oturtulması yazdığınız programlar için belge hazırlamanıza katkıda bulunacaktır.
6. Ve daha fazlası...

PEAR Kodlama standartları PEAR'ın resmi web sitesinde açıklanmıştır. Bu açıklamaların bir kısmını Türkçeleştirip bu yazıda size sunmaya çalışacağım.

<b>Satır uzunluğu ve girintiler</b>
Yaklaşık olarak 75-85 karakter aralığında yeni satıra geçilmelidir.

Girintiler ise 4 karakter uzunluğunda ve boşluk karakteri ile oluşturulmalıdır. Girintiler ayarlanırken sekme (tab karakteri) kullanılmamalıdır. Kod yazdığınız düzenleyicinin ayarlarını sekme uzunluğu 4 karakter ve boşluktan oluşacak şekilde ayarlamanız tavsiye edilmektedir.

<b>Kontrol İfadelerinin Yazılımı (IF, Switch)</b>
[php]
if ((koşul1) || (koşul2)) {
işlemler;
} elseif ((koşul3) && (koşul4)) {
diğer işlemler;
} else {
varsayılan işlemler;
}
[/php]

Kontrol ifadeleri (if, for, while, switch ...) yazılırken anahtar kelime ile parantez arasında bir boşluk olmalı ve mantıksal sınamaların yazımında her bir mantıksal ifade parantez ile ayrılmalı. Bu kodun okunabilirliğini artırdığı gibi mantıksal hataları yakalamanızı da sağlayacaktır.

Diğer bir örnek (Swicth)
[php]
switch (koşul) {
case 1:
Eylem1;
break;

case 2:
Eylem2;
break;

default:
varsayılan eylem;
break;
}
[/php]

<b>İşlev Çağrılması</b>
İşlev adı ile parantez arasında, ilk parametre ile parantez arasında ve son parametre ile parantez arasında boşluk [u]olmamalı[/u], parametreler birbirlerinden virgül ve boşluk karakteri ile ayrılmalı ve işlev tek bir satırda yazılıp noktalı virgül ile satır bitirilmelidir.

Örnek:
[php]
$var = foo($bar, $baz, $quux);
[/php]

Eşittir işareti ile işlev adı arasında bir boşluk olmalıdır, ancak kod okunurluğunun arttırılmasını sağlamak için duruma göre değişken adı ile eşittir işareti arasındaki boşluk miktarı artırılabilir.

[php]
$kisa = foo($bar);
$uzun_degisken = foo($baz);
[/php]

<b>İşlev Tanımlama</b>
İşlev tanımlamalarında kontrol ifadelerinden farklı olarak süslü parantez alt satırda yer alır.

Örnek:
[php]
function ornekIslev($arg1, $arg2 = '')
{
if (koşul) {
Eylem;
}
return $val;
}
[/php]

Varsayılan değere sahip parametreler son sıralarda tanımlanmalıdır.

Biraz daha uzun bir örnek
[php]
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}

if (!$dsninfo || !$dsninfo['phptype']) {
return $this->raiseError();
}

return true;
}
[/php]

<b>Yorum Satırları</b>
Yorum satırları phpDoc (www.phpdoc.org) standartına uygun yazılmalıdır.

Belge dışındaki yorum satırları standart C yorum satırları şeklinde olması tavsiye edilir (/* */ ve //) perl yorum satırı (#) benimsenmez.
<b>Kod dahil etme (include, require)</b>
Eğer bir sınıf (class) programa şarta bağlı olmaksızın dahil edilecekse <b>require_once()</b> kullanılmalıdır, ancak programın belli bir yerinde belli bir şarta bağlı olarak dahil edilmesi gerekiyorsa <b>include_once()</b> kullanılmalıdır.

[u]Not[/u]: <b>require_once()</b> ve <b>include_once()</b> işlev değil ifadedir. Dolayısıyla eklenecek dosya adı parantez içerisinde yazılmaz.

Örnek
[php]
require_once 'PEAR.php';
[/php]

<b>PHP etiketleri</b>
PHP başlangıç ve bitiş etiketleri olarak <?php ?> kullanılmalı. Daha kısa olan <? ?> kullanılmamalıdır.

<b>Sayfa Başı Yorum Satırları</b>

Bütün dosyalarda "sayfa seviyesi" (page level) yorum blokları sayfa başında yer almalı, "sınıf seviyesi" yorum satırları ise sınıf bildirisinin üzerinde yer almalıdır.

Aşağıdaki örneği inceleyiniz.

[php]
<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
* Dosya için kısa bir açıklama
*
* Eğer varsa dosya için daha uzun bir açıklama...
*
* PHP versions 4 and 5
*
* LICENSE: This source file is subject to version 3.0 of the PHP license
* that is available through the world-wide-web at the following URI:
* http://www.php.net/license/3_0.txt. If you did not receive a copy of
* the PHP License and are unable to obtain it through the web, please
* send a note to license@php.net so we can mail you a copy immediately.
*
* @category Kategori adı
* @package Paket adı
* @author Gerçek Yazar <yazar@example.com>
* @author Diğer Bir Yazar <digeri@example.com>
* @copyright 1997-2005 php.org.tr
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version CVS: $Id:$
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since File available since Release 1.2.0
* @deprecated File deprecated in Release 2.0.0
*/

/*
* Programa dahil edilmeler, sabit tanımlamaları ve $_GLOBAL
* ayarları burada yapılmalı.
* Yazdığınız yorum satırlarının phpDocumantor programına
* uygun olduğundan emin olmalısınız.
*/

/**
* Sınıf için kısa tanım.
*
* Eğer varsa sınıf için daha uzun tanım (açıklamalar)...
*
* @category Kategori adı
* @package Paket Adı
* @author Gerçek Yazar <yazar@example.com>
* @author Diğer Bir Yazar <digeri@example.com>
* @copyright 1997-2005 The PHP Group
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version Release: @package_version@
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class foo
{
}

?>
[/php]

<b>Dosya Başı Yorum Satırlarında Kullanılması Zorunlu Etiketler</b>

<i>Kısa Açıklama</i>: Kısa açıklama satırı bütün açıklama bloklarında yer almak zorundadır. Kısa açıklama satırı işlev, sınıf veya dosyanın adı olmamalı, ilgili nesneyi kısaca tarif edecek şekilde yapılmalıdır. Lütfen örnek dosyayı inceleyiniz.

<i>PHP Sürümü</i>: Aşağıdaki satırlardan birtanesi "dosya seviyesi" yorum bloğunda yer almak zorundadır.

[php]
* PHP version 4
* PHP version 5
* PHP versions 4 and 5
[/php]

<i>@license</i>: Pek çok açık kaynak lisans biçimi vardır. Aşağıdakilerden birisi "dosya seviyesi" ve "sınıf seviyesi" yorum bloklarında yer almak zorundadır. (PEAR için kod yazıyorsanız eğer..)

[php]
* @license http://www.apache.org/licenses/LICENSE-2.0 Apache License 2.0
* @license http://www.freebsd.org/copyright/freebsd-license.html BSD License (2 Clause)
* @license http://www.debian.org/misc/bsd.license BSD License (3 Clause)
* @license http://www.freebsd.org/copyright/license.html BSD License (4 Clause)
* @license http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
* @license http://www.php.net/license/3_0.txt PHP License 3.0
[/php]

Lisans ile ilgili daha fazla bilgi için PEAR grubunun [url=http://pear.php.net/group/docs/20040402-la.php]Lisans bildirilerine[/url] bakmalısınız.

<i>@link</i>: PEAR için yazılan programlarda aşağıdaki satır bulunmak zorundadır.

[php]
.
* @link http://pear.php.net/package/PackageName
[/php]

<i>@author</i>: Programa katkıda bulunan yazarların kaynak kodda yer almasıyla ilgili katı bir kural yoktur. Genellikle %10-%20 oranında programın değişmesini sağlanması veya bazı işlevlerin yeniden yazılması veya programa yeni bir mantık katılması kişiyi yazar listesine dahil etmek için yeterli görülür.

<i>@since</i>: Programın çıkarılan ilk sürümünden sonra kullanılması gerekir. İlgili dosyanının veya sınıfın hangi sürümden itibaren olduğunu belirtir. Programın çıkarılan ilk sürümünde bu etiket yer almaz.

<i>@deprecated</i>: Eğer dosya veya sınıf ilerki sürümlerde kullanılmaması planlıyorsa yazılması gerekir.

<b>Dosya Başı Yorum Satırlarında Kullanılması İsteğe Bağlı Etiketler</b>

<i>@copyright</i>: Telif hakkı bilgisini bildirir. Bu bilgiyi nasıl ekleyeceğinizde serbestsiniz. Kişi listesi, bir şirket ismi, belli bir gurup ismi yazabilirsiniz. Eğer yıl kullanacaksanız 4 haneli olmalı. Aşağıdaki örnekleri inceleyiniz.

[php]
.
* @copyright 2003 Sinan YALÇINKAYA ve Tufan ÖZSOY
* @copyright 2001-2004 Sinan YALÇINKAYA
* @copyright 1997-2004 POT
* @copyright 2001-2004 Fama Mühendislik
[/php]

<i>Lisans Özeti</i>: Eğer PHP lisansıyla yazacaksanız yukardaki örneği olduğu gibi kullanabilirsiniz. Veya isteğinize göre bir lisans dosyası yazabilirsiniz. Dikkat etmeniz gereken şey yazdığınız lisans dosyasının <pre>LICENCE:</pre> şeklinde başlamasıdır.

<i>@see</i>: Nesne ile ilgili olan diğer nesnelere (sınıf, dosya, işlev, değişken...) atıfta bulunurken kullanılır. Birden fazla @see etiketi yazmaktansa bağlantılı olan nesneleri virgül ile ayırıp yan yana yazmak tavsiye edilir.

<b>Örnek Adresler</b>

Bütün örnek adresler [url=http://www.faqs.org/rfcs/rfc2606]rfc2606[/url] standartına göre <pre>example.com, example.org ve example.org</pre> şeklinde verilmelidir.

<b>İsimlendirme</b>

<i>Sınıflar</i>: Sınıf isimleri büyük harf ile başlamalı, mümkün olduğunca kısaltma kullanılmalıdır. Sınıf hiyerarşisi içerisinde her bir alt seviye tek bir alt çizgi işareti ile ayrılmalıdır.

Örnek:
Log
Net_Finger
HTML_Upload_Error

<i>İşlevler</i>: İşlev isimleri kısaltmalar hariç küçük harf ile başlayıp devam eder, ancak yeni bir kelimeye geçeceksek sınıf isimlerindeki gibi alt çizgi kullanmak yerine yeni kelimenin ilk harfini büyük yazarız.

Örnekler:
baglan()
veriAl()
birSeylerYap()
XML_RPC_serializeData()

Sınıfa ait "özel" (sadece sınıf tarafından kullanılacak) işlevler isimlendirilirken ilk karakter olarak alt çizgi kullanır ve işlev isimlendirme kurallarına göre isimlendiririz.

Örnekler:
_sort()
_initTree()
$this->_status

<i>Sabitler</i>: Sınıf isimleri her zaman büyük harflerle yazılmalı ve her bir kelime alt çizgi ile birbirinden ayrılmalıdır. Sabitlerin ön ekleri daima ilgili paketin adı ile başlamalı ve alt çizgi ile diğer kelimeden ayrılmalıdır. Örneğin PEAR'ın DB:: paketine ait bütün sabit isimleri DB_ ile başlamalıdır.

[u]Not[/u]: <i>true</i>, <i>false</i> ve <i>null</i> sabitleri diğerlerinden ayrı olarak daima küçük harflerle yazılmak zorundadır.

<i>Global Değişkenler</i>: Eğer paketiniz global değişkenler kullanacaksa bu değişkenler alt çizgi, paketin adı ve tekrar alt çizgi ile başlamalıdır. Örnek olarak PEAR paketi aşağıdaki gibi bir global değişken tanımlamıştır.

[php]
$_PEAR_destructor_object_list
[/php]

<b>Dosya Biçimi</b>
PEAR için yazılacak her program dosyası aşağıdaki niteliklerde olmalıdır.

* ASCII text olarak kaydedilmeli.
* ISO-8859-1 karakter kodlamasıyla kaydedilmeli.
* Unix dosya biçimi şeklinde olmalı.

Unix dosya biçiminden kasıt satırların <i>LR</i> özel etiketi ile bölünmesi, windowsta olduğu gibi <i>CLRF</i> veya machintosh da olduğu gibi <i>CL</i> ile değil. Ve dosyanın en son karakterlerinin ?> olması (PHP bitiş etiketinden sonra her hangi bir boş satır veya boşluk vs... olmamasına dikkat etmelisiniz)

<b>Örnek Dosya</b>

[php]
<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */


/**
* Dosya için kısa bir açıklama
*
* Eğer varsa dosya için daha uzun bir açıklama...
*
* PHP versions 4 and 5
*
* LICENSE: This source file is subject to version 3.0 of the PHP license
* that is available through the world-wide-web at the following URI:
* http://www.php.net/license/3_0.txt. If you did not receive a copy of
* the PHP License and are unable to obtain it through the web, please
* send a note to license@php.net so we can mail you a copy immediately.
*
* @category Kategori adı
* @package Paket adı
* @author Gerçek Yazar <yazar@example.com>
* @author Diğer Bir Yazar <digeri@example.com>
* @copyright 1997-2005 php.org.tr
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version CVS: $Id:$
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since File available since Release 1.2.0
* @deprecated File deprecated in Release 2.0.0
*/

/**
* Bu bir "Belge yorumu" ("Docblock Comment,") bloğudur. Daha çok "docblock"
* olarak bilinir. Bu yorum satırlarının nasıl yazıldığı ile ilgili daha
* fazla açıklama alt satırlarda yer almaktadır.
*/
require_once 'PEAR.php';

// {{{ constants

/**
* Yöntem başarılı olduğunda bu değeri döndürecek.
*/
define('NET_SAMPLE_OK', 1);

// }}}
// {{{ GLOBALS

/**
* Kaç nesnenin yaratılacağı
* @global int $GLOBALS['NET_SAMPLE_Count']
*/
$GLOBALS['NET_SAMPLE_Count'] = 0;

// }}}
// {{{ Net_Sample

/**
* PEAR Standartlarına göre nasıl kod yazılacağına dair bir örnek
*
* Belge yorumları "/**" işareti ile başlar. "/" işareti normal girinti
* yerinde olmalı ve yıldız işaretleri ise bir karakter içeride, ilk yıldız
* işaretinin altına denk gelecek şekilde yer almalı. Belge yorum bloklarının
* son satırı "*/" işaretiyle kapatılmalı. Yıldız ile başlamayan satır
* eklemeyin. Paragraflar arasında boş bir satır bırakın. Açıklama
* paragrafları ile, @ ile başlayan etiketlerin yazıldığı blok arasındada
* bir satır boşluk bırakın. Yorum satırlarını 80. karakterden önce kesin.
*
* Belge yorum blokları sadece programın yapı taşları için kullanılır. Belge
* yorum bloğu yazılmasına izin verilenler "classes, properties, methods,
* includes, globals" olarak tanımlanmıştır.
* Daha fazla bilgi için phpDocumentor'un sayfasını ziyaret edin
* http://phpdoc.org/docs/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html
*
* Jovadocs Style Rehberi belge yorum blokları yazarken nelere dikkat etmemiz
* gerektiğini güzel bir şekilde anlatır. Aşağıdaki adreste bununla ilgili
* güzel bir belgeye ulaşabilirsiniz.
* http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide
*
* Herhangi bir belge yorum bloğunun ilk satırı özet olmalıdır. Özet satırını
* kısa bir başlık gibi hazırlamalısınız. Sınıf, özellik ve sabitler için
* kısaca tanımlayacak şekilde yazmalısınız. Bunların hareket ve davranışlarını
* anlatmaktan çok özet satırında kısaca tanımlamaya çalışmalısınız.
*
* Aşağıdaki etiketler yaygın olarak kullanılan etiketlerdir. @category den
* @access e kadar olan kısım mecburidir. phpDocumantor bunlardan başka
* bir çok etiketi destekler. Bu diğer etiketleri kullanmakta serbestsiniz.
*
* @category KategoriAdı
* @package PaketAdı
* @author Asıl Yazar <author@example.com>
* @author Yardımcı Yazar <another@example.com>
* @copyright 1997-2005 The PHP Group
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version Release: @package_version@
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class Net_Sample
{
// {{{ Nitelikler

/**
* The status of foo's universe
*
* Potential values are 'good', 'fair', 'poor' and 'unknown'.
*
* @var string
*/
var $foo = 'unknown';

/**
* The status of life
*
* Note that names of private properties or methods must be
* preceeded by an underscore.
*
* @var bool
* @access private
*/
var $_good = true;

// }}}
// {{{ setFoo()

/**
* Registers the status of foo's universe
*
* Summaries for methods should use 3rd person declarative rather
* than 2nd person imperative, begining with a verb phrase.
*
* Summaries should add description beyond the method's name. The
* best method names are "self-documenting", meaning they tell you
* basically what the method does. If the summary merely repeats
* the method name in sentence form, it is not providing more
* information.
*
* Summary Examples:
* + Sets the label (preferred)
* + Set the label (avoid)
* + This method sets the label (avoid)
*
* Below are the tags commonly used for methods. A @param tag is
* required for each parameter the method has. The @return and
* @access tags are mandatory. The @throws tag is required if the
* method uses exceptions. @static is required if the method can
* be called statically. The remainder should only be used when
* necessary. Please use them in the order they appear here.
* phpDocumentor has several other tags available, feel free to use
* them.
*
* The @param tag contains the data type, then the parameter's
* name, followed by a description. By convention, the first noun in
* the description is the data type of the parameter. Articles like
* "a", "an", and "the" can precede the noun. The descriptions
* should start with a phrase. If further description is necessary,
* follow with sentences. Having two spaces between the name and the
* description aids readability.
*
* When writing a phrase, do not capitalize and do not end with a
* period:
* + the string to be tested
*
* When writing a phrase followed by a sentence, do not capitalize the
* phrase, but end it with a period to distinguish it from the start
* of the next sentence:
* + the string to be tested. Must use UTF-8 encoding.
*
* Return tags should contain the data type then a description of
* the data returned. The data type can be any of PHP's data types
* (int, float, bool, string, array, object, resource, mixed)
* and should contain the type primarily returned. For example, if
* a method returns an object when things work correctly but false
* when an error happens, say 'object' rather than 'mixed.' Use
* 'void' if nothing is returned.
*
* Here's an example of how to format examples:
* <sample>
* require_once 'Net/Sample.php';
*
* $s = new Net_Sample();
* if (PEAR::isError($s)) {
* echo $s->getMessage() . "\n";
* }
* </sample>
*
* @param string $arg1 the string to quote
* @param int $arg2 an integer of how many problems happened.
* Indent to the description's starting point
* for long ones.
*
* @return int the integer of the set mode used. FALSE if foo
* foo could not be set.
* @throws exceptionclass [description]
*
* @access public
* @static
* @see Net_Sample::$foo, Net_Other::someMethod()
* @since Method available since Release 1.2.0
* @deprecated Method deprecated in Release 2.0.0
*/
function setFoo($arg1, $arg2 = 0)
{
/*
* This is a "Block Comment." The format is the same as
* Docblock Comments except there is only one asterisk at the
* top. phpDocumentor doesn't parse these.
*/
if ($arg1 == 'good' || $arg1 == 'fair') {
$this->foo = $arg1;
return 1;
} elseif ($arg1 == 'poor' && $arg2 > 1) {
$this->foo = 'poor';
return 2;
} else {
return false;
}
}

// }}}
}

// }}}

/*
* Local variables:
* tab-width: 4
* c-basic-offset: 4
* c-hanging-comment-ender-p: nil
* End:
*/

?>
[/php]
Remarks

prev (10) overview next (12)

CyberChair Author: Richard van de Stadt  (Borbala Online Conference Services) Development supported by TRESE Copyright © by University of Twente