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ı, iki ana ayrım dışında PSR-12 Extended Coding Style standardına karşılık gelir: girinti için boşluk yerine sekme kullanır ve sınıf sabitleri için PascalCase kullanır.

Bu kuralların çoğu Nette 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
• Arayüzler ve soyut sınıflar önek ya da sonek içermemelidir, ö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:

	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

/**
 * 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:

/** @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.