Kodlama standardı

Bu belge, Nette geliştirme için kuralları ve önerileri açıklar. Nette'ye kod katkısında bulunurken bunlara uymalısınız. Bunu yapmanın en kolay yolu, mevcut kodu taklit etmektir. Amaç, tüm kodun tek bir kişi tarafından yazılmış gibi görünmesidir.

Nette Kodlama Standardı, iki ana istisna dışında PSR-12 Genişletilmiş Kodlama Stili ile uyumludur: girinti için boşluklar yerine sekmeler kullanır ve sınıf sabitleri için PascalCase kullanır.

Genel kurallar

• Her PHP dosyası declare(strict_types=1) içermelidir
• Daha iyi okunabilirlik için metotları ayırmak için iki boş satır kullanılır.
• Susturma operatörünün (@) kullanım nedeni belgelenmelidir: @mkdir($dir); // @ - dizin mevcut olabilir.
• Zayıf tipli bir karşılaştırma operatörü (yani ==, !=, …) kullanılıyorsa, amaç belgelenmelidir: // == null kabul et
• Tek bir exceptions.php dosyasına birden fazla istisna yazabilirsiniz.
• Arayüzler için metot görünürlüğü belirtilmez, çünkü her zaman public'tirler.
• Her özellik, dönüş değeri ve parametre için bir tip belirtilmelidir. Tersine, nihai sabitler için tipi asla belirtmeyiz, çünkü açıktır.
• Bir karakter dizisini sınırlamak için, değişmez değerin kendisi kesme işareti içermediği sürece tek tırnak işaretleri kullanılmalıdır.

Adlandırma kuralları

• Tam ad çok uzun olmadıkça kısaltmalar kullanmayın.
• İki harfli kısaltmalar için büyük harfler, daha uzun kısaltmalar için pascal/camel case kullanın.
• Sınıf adı için bir isim veya isim tamlaması kullanın.
• Sınıf adları yalnızca özgüllüğü (Array) değil, aynı zamanda genelliği de (ArrayIterator) içermelidir. PHP dil nitelikleri bir istisnadır.
• Sınıf sabitleri ve enumlar PascalCaps kullanmalıdır.
• Arayüzler ve soyut sınıflar, Abstract, Interface veya I gibi önekler veya sonekler içermemelidir.

Sarma ve Parantezler

Nette Kodlama Standardı, PSR-12 (veya PER Kodlama Stili) ile uyumludur, bazı noktalarda onu tamamlar veya değiştirir:

• ok fonksiyonları parantezden önce boşluk olmadan yazılır, yani fn($a) => $b
• farklı use import ifadeleri türleri arasında boş bir satır gerekli değildir
• fonksiyon/metot dönüş tipi ve açılış küme parantezi her zaman ayrı satırlardadır:

	public function find(
		string $dir,
		array $options,
	): array
	{
		// metot gövdesi
	}

Ayrı bir satırdaki açılış küme parantezi, fonksiyon/metot imzasını gövdeden görsel olarak ayırmak için önemlidir. İmza tek bir satırdaysa, ayırma açıktır (soldaki resim), birden çok satırdaysa, PSR'de imzalar ve gövde birleşir (ortada), Nette standardında ise ayrı kalırlar (sağda):

Belgelendirme blokları (phpDoc)

Ana kural: Ek bir değer olmadan parametre tipi veya dönüş tipi gibi imzadaki hiçbir bilgiyi asla tekrarlamayın.

Sınıf tanımı için belgelendirme bloğu:

• Sınıfın bir açıklamasıyla başlar.
• Ardından boş bir satır gelir.
• Ardından @property (veya @property-read, @property-write) ek açıklamaları gelir, birbiri ardına. Sözdizimi: ek açıklama, boşluk, tip, boşluk, $name.
• Ardından @method ek açıklamaları gelir, birbiri ardına. Sözdizimi: ek açıklama, boşluk, dönüş tipi, boşluk, name(tip $param, …).
• @author ek açıklaması atlanır. Yazarlık, kaynak kodu geçmişinde tutulur.
• @internal veya @deprecated ek açıklamaları kullanılabilir.

/**
 * MIME mesaj bölümü.
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */

Yalnızca @var ek açıklamasını içeren bir özellik için belgelendirme bloğu tek satırlık olmalıdır:

/** @var string[] */
private array $name;

Metot tanımı için belgelendirme bloğu:

• Metodun kısa bir açıklamasıyla başlar.
• Boş satır yok.
• Ayrı satırlarda @param ek açıklamaları.
• @return ek açıklaması.
• @throws ek açıklamaları, birbiri ardına.
• @internal veya @deprecated ek açıklamaları kullanılabilir.

Her ek açıklamayı bir boşluk takip eder, @param hariç, daha iyi okunabilirlik için bunu iki boşluk takip eder.

/**
 * Dizinde bir dosya bulur.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array

Boşluklar yerine sekmeler

Sekmelerin boşluklara göre birkaç avantajı vardır:

• girinti boyutu düzenleyicilerde ve web'de ayarlanabilir
• kodun kullanıcının girinti boyutu tercihini zorlamazlar, bu nedenle kod daha taşınabilirdir
• tek bir tuş vuruşuyla yazılabilirler (sadece sekmeleri boşluklara dönüştüren düzenleyicilerde değil, her yerde)
• girintileme onların amacıdır
• görme engelli ve kör meslektaşlarımızın ihtiyaçlarına saygı duyarlar

Projelerimizde sekmeler kullanarak, çoğu insan için gereksiz görünebilecek genişlik ayarlamasına izin veriyoruz, ancak görme engelli insanlar için bu zorunludur.

Braille ekranları kullanan kör programcılar için her boşluk bir Braille hücresini temsil eder. Bu nedenle, varsayılan girinti 4 boşluksa, 3. seviye girinti, kod başlamadan önce 12 değerli Braille hücresini boşa harcar. Dizüstü bilgisayarlarda en sık kullanılan 40 hücreli bir ekranda, bu, herhangi bir bilgi olmadan boşa harcanan mevcut hücrelerin dörtte birinden fazlasıdır.