Kodlama Standardı
*****************
.[perex]
Bu belge, Nette'in geliştirilmesine ilişkin kuralları ve önerileri anlatır. Nette'e kod katkısı yaparken onlara uymalısınız. Bunu yapmanın en kolay yolu var olan kodu taklit etmektir. Amaç, tüm kodun tek bir kişi tarafından yazılmış gibi görünmesidir.
Nette Kodlama Standardı, iki ana ayrım dışında [PSR-12 Extended Coding Style |https://www.php-fig.org/psr/psr-12/] standardına karşılık gelir: girinti için [boşluk yerine sekme |#Boşluk Yerine Sekme] kullanır ve [sınıf sabitleri için PascalCase|https://blog.nette.org/tr/for-less-screaming-in-the-code] kullanır.
.[tip]
Bu kuralların çoğu [Nette Coding Standard |tools:coding-standard] aracıyla otomatik denetlenip düzeltilebilir, dolayısıyla onları elle denetlemeniz gerekmez.
Genel Kurallar
==============
- Her PHP dosyası `declare(strict_types=1)` içermelidir
- Daha iyi okunabilirlik için metotları ayırmak üzere iki boş satır kullanılır
- Sustur operatörünün (`@`) kullanım nedeni belgelenmelidir: `@mkdir($dir); // @ - directory may exist`
- Zayıf tipli bir karşılaştırma operatörü kullanılıyorsa (yani `==`, `!=`, ...), niyet belgelenmelidir: `// == to accept null`
- Birden çok istisna sınıfını `exceptions.php` adlı tek bir dosyaya, birden çok enum'ı ise `enums.php` dosyasına yazabilirsiniz
- Arayüzlerde metotların görünürlüğü belirtilmez, çünkü onlar her zaman geneldir
- Her özelliğin, dönüş değerinin ve parametrenin tipi belirtilmelidir. Tersine, final sabitler için tipi asla belirtmeyiz, çünkü apaçıktır
- Dizeleri sınırlamak için tek tırnak kullanılmalıdır; ancak dizenin kendisi kesme işareti içeriyorsa değil
Adlandırma Kuralları
====================
- Tam ad aşırı uzun değilse kısaltma kullanmaktan kaçının
- İki harfli kısaltmalar için büyük harf, daha uzun kısaltmalar için PascalCase/camelCase kullanın
- Sınıf adı için bir ad ya da ad öbeği kullanın
- Sınıf adları yalnızca özgüllüğü (`Array`) değil, genelliği de (`ArrayIterator`) içermelidir. PHP nitelikleri bunun dışındadır
- "Sınıf sabitleri ve enum'lar PascalCaps kullanmalıdır":https://blog.nette.org/tr/for-less-screaming-in-the-code
- "Arayüzler ve soyut sınıflar önek ya da sonek içermemelidir":https://blog.nette.org/tr/prefixes-and-suffixes-do-not-belong-in-interface-names, örneğin `Abstract`, `Interface` ya da `I`
Satır Sarma ve Parantezler
==========================
Nette Kodlama Standardı PSR-12 (ya da PER Coding Style) standardına karşılık gelir, ama onu bazı noktalarda özelleştirir ya da değiştirir:
- Ok fonksiyonları parantezden önce boşluk olmadan yazılır, yani `fn($a) => $b`
- Farklı `use` import deyimi tipleri arasında boş satır gerekmez
- Bir fonksiyonun/metodun dönüş tipi ile açılan süslü parantez her zaman ayrı satırlardadır:
```php
public function find(
string $dir,
array $options,
): array
{
// method body
}
```
Açılan süslü parantezin ayrı satırda olması, fonksiyon/metot imzasını gövdeden görsel olarak ayırmak açısından önemlidir. İmza tek satırdaysa ayrım açıktır (soldaki görsel). Birden çok satırdaysa, PSR'de imza ile gövde birbirine karışır (ortada), Nette standardında ise ayrı kalırlar (sağda):
[* new-line-after.webp *]
Belge Blokları (phpDoc)
=======================
Ana kural: Parametre tipi ya da dönüş tipi gibi imza bilgilerini, değer katmadan **asla yinelemeyin**.
Bir sınıf tanımı için belge bloğu:
- Sınıfın açıklamasıyla başlar
- Ardından boş bir satır gelir
- Ardından, her satıra bir tane olmak üzere `@property` (ya da `@property-read`, `@property-write`) açıklamaları gelir. Sözdizimi: açıklama, boşluk, tip, boşluk, `$name`
- Ardından, her satıra bir tane olmak üzere `@method` açıklamaları gelir. Sözdizimi: açıklama, boşluk, dönüş tipi, boşluk, `name(type $param, ...)`
- `@author` açıklaması atlanır. Yazarlık, kaynak kodun geçmişinde tutulur
- `@internal` ya da `@deprecated` açıklamaları kullanılabilir
```php
/**
* MIME message part.
*
* @property string $encoding
* @property-read array $headers
* @method string getSomething(string $name)
* @method static bool isEnabled()
*/
```
Yalnızca `@var` açıklamasını içeren, bir özelliğe ait belge bloğu tek satırda olmalıdır:
```php
/** @var string[] */
private array $name;
```
Bir metot tanımı için belge bloğu:
- Metodun kısa bir açıklamasıyla başlar
- Boş satır yok
- Her satıra bir tane olmak üzere `@param` açıklamaları
- `@return` açıklaması
- Her satıra bir tane olmak üzere `@throws` açıklamaları
- `@internal` ya da `@deprecated` açıklamaları kullanılabilir
Her açıklamadan sonra bir boşluk gelir; daha iyi okunabilirlik için iki boşluk gelen `@param` bunun dışındadır.
```php
/**
* Finds a file in directory.
* @param string[] $options
* @return string[]
* @throws DirectoryNotFoundException
*/
public function find(string $dir, array $options): array
```
Küresel Fonksiyonlar ve Sabitler
================================
Küresel fonksiyonlar ve sabitler baştaki ters eğik çizgi olmadan yazılır, yani `\count($arr)` değil `count($arr)`. PHP'nin iyileştirebildiği fonksiyonlar için, derleyicinin onları daha verimli çevirebilmesi amacıyla dosyanın başına `use function` ekleyin. Bunlar arasında `count`, `strlen`, `is_array`, `is_string`, `is_scalar`, `sprintf` gibi fonksiyonlar vardır. Import bloğunu derli toplu tutmak için fonksiyonlar tek satırda listelenir:
```php
use Nette;
use function count, is_array, is_scalar, sprintf;
```
Ara sıra, değerinin bilinmesi derleyiciye yardım edebilecek sabitleri de import ederiz:
```php
use const PHP_OS_FAMILY;
```
Boşluk Yerine Sekme
===================
Sekmelerin boşluklara göre birkaç avantajı vardır:
- Girintinin boyutu düzenleyicilerde ve "web'de":https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size özelleştirilebilir
- Kullanıcının girinti boyutu tercihini koda dayatmazlar, bu da kodu daha taşınabilir kılar
- Tek tuş vuruşuyla yazılabilirler (yalnızca sekmeleri boşluğa çeviren düzenleyicilerde değil, her yerde)
- Girinti onların varlık nedenidir
- Görme engelli ve kör meslektaşların gereksinimlerine saygı gösterirler
Projelerimizde sekme kullanarak genişlik özelleştirmesine olanak tanırız; bu çoğu insana gereksiz görünebilir, ama görme engelli insanlar için temeldir.
Braille ekran kullanan kör programcılar için her boşluk bir braille hücresini temsil eder. Yani varsayılan girinti 4 boşluksa, 3. düzey bir girinti, kod daha başlamadan 12 değerli braille hücresini harcar. Dizüstü bilgisayarlarda en yaygın olan 40 hücrelik bir ekranda bu, kullanılabilir hücrelerin dörtte birinden fazlasının hiçbir bilgi vermeden harcanması demektir.
{{priority: -1}}
Kodlama Standardı
Bu belge, Nette'in geliştirilmesine ilişkin kuralları ve önerileri anlatır. Nette'e kod katkısı yaparken
onlara uymalısınız. Bunu yapmanın en kolay yolu var olan kodu taklit etmektir. Amaç, tüm kodun tek bir kişi tarafından
yazılmış gibi görünmesidir.
Nette Kodlama Standardı PSR-12 (ya da PER Coding Style) standardına karşılık gelir, ama onu bazı noktalarda
özelleştirir ya da değiştirir:
Ok fonksiyonları parantezden önce boşluk olmadan yazılır, yani fn($a) => $b
Farklı use import deyimi tipleri arasında boş satır gerekmez
Bir fonksiyonun/metodun dönüş tipi ile açılan süslü parantez her zaman ayrı satırlardadır:
public function find(
string $dir,
array $options,
): array
{
// method body
}
Açılan süslü parantezin ayrı satırda olması, fonksiyon/metot imzasını gövdeden görsel olarak ayırmak açısından
önemlidir. İmza tek satırdaysa ayrım açıktır (soldaki görsel). Birden çok satırdaysa, PSR'de imza ile gövde birbirine
karışır (ortada), Nette standardında ise ayrı kalırlar (sağda):
Belge Blokları (phpDoc)
Ana kural: Parametre tipi ya da dönüş tipi gibi imza bilgilerini, değer katmadan asla yinelemeyin.
Bir sınıf tanımı için belge bloğu:
Sınıfın açıklamasıyla başlar
Ardından boş bir satır gelir
Ardından, her satıra bir tane olmak üzere @property (ya da @property-read,
@property-write) açıklamaları gelir. Sözdizimi: açıklama, boşluk, tip, boşluk, $name
Ardından, her satıra bir tane olmak üzere @method açıklamaları gelir. Sözdizimi: açıklama, boşluk,
dönüş tipi, boşluk, name(type $param, ...)
@author açıklaması atlanır. Yazarlık, kaynak kodun geçmişinde tutulur
@internal ya da @deprecated açıklamaları kullanılabilir
Yalnızca @var açıklamasını içeren, bir özelliğe ait belge bloğu tek satırda olmalıdır:
/** @var string[] */
private array $name;
Bir metot tanımı için belge bloğu:
Metodun kısa bir açıklamasıyla başlar
Boş satır yok
Her satıra bir tane olmak üzere @param açıklamaları
@return açıklaması
Her satıra bir tane olmak üzere @throws açıklamaları
@internal ya da @deprecated açıklamaları kullanılabilir
Her açıklamadan sonra bir boşluk gelir; daha iyi okunabilirlik için iki boşluk gelen @param bunun
dışındadır.
/**
* Finds a file in directory.
* @param string[] $options
* @return string[]
* @throws DirectoryNotFoundException
*/
public function find(string $dir, array $options): array
Küresel Fonksiyonlar ve Sabitler
Küresel fonksiyonlar ve sabitler baştaki ters eğik çizgi olmadan yazılır, yani \count($arr) değil
count($arr). PHP'nin iyileştirebildiği fonksiyonlar için, derleyicinin onları daha verimli çevirebilmesi
amacıyla dosyanın başına use function ekleyin. Bunlar arasında count, strlen,
is_array, is_string, is_scalar, sprintf gibi fonksiyonlar vardır. Import
bloğunu derli toplu tutmak için fonksiyonlar tek satırda listelenir:
use Nette;
use function count, is_array, is_scalar, sprintf;
Ara sıra, değerinin bilinmesi derleyiciye yardım edebilecek sabitleri de import ederiz:
use const PHP_OS_FAMILY;
Boşluk Yerine Sekme
Sekmelerin boşluklara göre birkaç avantajı vardır:
Girintinin boyutu düzenleyicilerde ve web'de
özelleştirilebilir
Kullanıcının girinti boyutu tercihini koda dayatmazlar, bu da kodu daha taşınabilir kılar
Tek tuş vuruşuyla yazılabilirler (yalnızca sekmeleri boşluğa çeviren düzenleyicilerde değil, her yerde)
Girinti onların varlık nedenidir
Görme engelli ve kör meslektaşların gereksinimlerine saygı gösterirler
Projelerimizde sekme kullanarak genişlik özelleştirmesine olanak tanırız; bu çoğu insana gereksiz görünebilir, ama
görme engelli insanlar için temeldir.
Braille ekran kullanan kör programcılar için her boşluk bir braille hücresini temsil eder. Yani varsayılan girinti
4 boşluksa, 3. düzey bir girinti, kod daha başlamadan 12 değerli braille hücresini harcar. Dizüstü bilgisayarlarda en
yaygın olan 40 hücrelik bir ekranda bu, kullanılabilir hücrelerin dörtte birinden fazlasının hiçbir bilgi vermeden
harcanması demektir.