Kodlama Standardı

Bu belgede Nette'i geliştirmek için kurallar ve öneriler açıklanmaktadır. Nette'ye kod katkısında bulunurken bunlara uymalısınız. Bunu yapmanın en kolay yolu mevcut kodu taklit etmektir. Buradaki fikir, tüm kodun tek bir kişi tarafından yazılmış gibi görünmesini sağlamaktır.

Nette Kodlama Standardı, iki ana istisna dışında PSR-12 Genişletilmiş Kodlama Stiline karşılık gelir: girinti için boşluk yerine sekme kullanır ve sınıf sabitleri için PascalCase kullanır.

Genel Kurallar

• Her PHP dosyası şunları içermelidir declare(strict_types=1)
• Daha iyi okunabilirlik için yöntemleri ayırmak için iki boş satır kullanılır.
• Susma operatörünün kullanım nedeni belgelenmelidir: @mkdir($dir); // @ - directory may exist
• Zayıf tipli karşılaştırma operatörü kullanılırsa (örn. ==, !=, …), niyet belgelenmelidir: // == to accept null
• Bir dosyaya daha fazla istisna yazabilirsiniz exceptions.php
• Yöntemlerin görünürlüğü arayüzler için belirtilmez çünkü bunlar her zaman public'tir.
• Her özellik, geri dönüş değeri ve parametre için bir tür belirtilmelidir. Öte yandan, nihai sabitler için türü asla belirtmeyiz çünkü bu açıktır.
• Değişmezin kendisi kesme işareti içermediği sürece, dizeyi sınırlandırmak için tek tırnak kullanılmalıdır.

Adlandırma Kuralları

• Tam ad aşırı olmadığı sürece kısaltma kullanmaktan kaçının.
• İki harfli kısaltmalar için büyük harf, daha uzun kısaltmalar için küçük/büyük harf kullanın.
• Sınıf adı için bir isim veya isim cümlesi kullanın.
• Sınıf adları sadece özgüllük (Array) değil, aynı zamanda genellik (ArrayIterator) de içermelidir. PHP öznitelikleri istisnadır.
• Sınıf sabitleri ve enumlar PascalCaps kullanmalıdır.
• Arayüzler ve soyut sınıflar Abstract, Interface veya I gibi ön ekler veya son ekler içermemelidir.

Sargı ve Teller

Nette Kodlama Standardı PSR-12'ye (veya PER Kodlama Stiline) karşılık gelir, bazı noktalarda onu daha fazla belirtir veya değiştirir:

• ok fonksiyonları parantezden önce boşluk bırakılmadan yazılır, yani fn($a) => $b
• use import ifadelerinin farklı türleri arasında boş satır gerekmez
• Bir fonksiyonun/metodun dönüş tipi ve açılış küme parantezi her zaman ayrı satırlarda yer alır:

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

Ayrı bir satırda açılan küme parantezi, fonksiyon/metot imzasını gövdeden görsel olarak ayırmak için önemlidir. İmza tek bir satırdaysa, ayrım nettir (soldaki resim), birden fazla satırdaysa, PSR'de imzalar ve gövdeler birbirine karışırken (ortada), Nette standardında ayrı kalırlar (sağda):

Dokümantasyon Blokları (phpDoc)

Ana kural: parametre tipi veya dönüş tipi gibi hiçbir imza bilgisini ek bir değer olmadan asla çoğaltmayın.

Sınıf tanımı için dokümantasyon bloğu:

• Bir sınıf tanımıyla başlar.
• Boş satır takip eder.
• @property (veya @property-read, @property-write) ek açıklamaları satır satır takip eder. Sözdizimi şöyledir: açıklama, boşluk, tür, boşluk, $name.
• @method ek açıklamaları satır satır takip eder. Sözdizimi: açıklama, boşluk, dönüş tipi, boşluk, isim(tip $param, …).
• @author ek açıklaması atlanmıştır. Yazarlık bir kaynak kodu geçmişinde tutulur.
• @internal veya @deprecated ek 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 ek açıklamasını içeren özellik için dokümantasyon bloğu tek satırda olmalıdır:

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

Yöntem tanımı için dokümantasyon bloğu:

• Kısa bir yöntem açıklaması ile başlar.
• Boş satır yoktur.
• @param ek açıklamaları, tek tek satır.
• @return ek açıklaması.
• @throws ek açıklamaları, tek tek satır.
• @internal veya @deprecated ek açıklamaları kullanılabilir.

Daha iyi okunabilirlik için iki boşluk ile takip edilen @param haricinde her ek açıklamadan sonra bir boşluk bırakılır.

/**
 * Finds a file in directory.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array

Boşluklar Yerine Sekmeler

Sekmelerin boşluklara göre çeşitli avantajları vardır:

• girinti boyutu editörlerde ve webde özelleştirilebilir
• kullanıcının girinti boyutu tercihini koda empoze etmezler, bu nedenle kod daha taşınabilirdir
• bunları tek bir tuşa basarak yazabilirsiniz (sadece sekmeleri boşluğa dönüştüren editörlerde değil, her yerde)
• girinti onların amacıdır
• görme engelli ve görme engelli meslektaşlarının ihtiyaçlarına saygı duymak

Projelerimizde sekmeler kullanarak, çoğu insan için gereksiz görünebilecek, ancak görme engelli kişiler için çok önemli olan genişlik özelleştirmesine izin veriyoruz.

Braille ekran kullanan görme engelli programcılar için her boşluk bir braille hücresi ile temsil edilir ve değerli bir alan kaplar. Yani varsayılan girinti 4 boşluksa, 3. seviye bir girinti kod başlamadan önce 12 braille hücresini boşa harcar. Dizüstü bilgisayarlarda en yaygın olarak kullanılan 40 hücreli bir ekranda, bu, mevcut hücrelerin dörtte birinden fazlasının herhangi bir bilgi olmadan boşa harcanması anlamına gelir.