コーディング規約
********

.[perex]
この文書は Nette を開発するときの決まりとおすすめをまとめたものです。Nette にコードを貢献するときは、これに従わなければなりません。いちばん簡単なやり方は、既存のコードをまねることです。目指すのは、すべてのコードがひとりの人によって書かれたように見えることです。

Nette のコーディング規約は [PSR-12 Extended Coding Style |https://www.php-fig.org/psr/psr-12/]に沿っていますが、大きな違いが 2 つあります。字下げに[空白ではなくタブ |#空白ではなくタブ]を使うことと、[クラスの定数に PascalCase|https://blog.nette.org/en/for-less-screaming-in-the-code]を使うことです。

.[tip]
これらの決まりの多くは [Nette Coding Standard |tools:coding-standard]の道具が自動的に確かめて直せるので、手で確かめる必要はありません。


全般の決まり
======

- すべての PHP のファイルには `declare(strict_types=1)` を入れます
- 読みやすさのために、メソッドのあいだは空行 2 つで区切ります
- 黙らせる演算子（`@`）を使う理由は書き残さなければなりません。`@mkdir($dir); // @ - directory may exist`
- 緩い型の比較の演算子（つまり `==`、`!=` など）を使うなら、その意図を書き残さなければなりません。`// == to accept null`
- 例外のクラスは `exceptions.php` という名前のひとつのファイルに複数書けますし、enum は `enums.php` に複数書けます
- インターフェースではメソッドの可視性を書きません。いつも public だからです
- すべてのプロパティ、戻り値、パラメータには型を指定しなければなりません。逆に final の定数には型を決して書きません。自明だからです
- 文字列は単一引用符で囲むべきです。ただしその文字列自身がアポストロフィを含む場合は別です


名前の付け方
======

- 完全な名前が長すぎる場合を除き、省略形は避けます
- 2 文字の省略形は大文字にし、それより長い省略形は PascalCase／camelCase にします
- クラス名には名詞か名詞句を使います
- クラス名には具体さ（`Array`）だけでなく一般さ（`ArrayIterator`）も含めなければなりません。PHP のアトリビュートは例外です
- "クラスの定数と enum は PascalCaps を使うべきです":https://blog.nette.org/en/for-less-screaming-in-the-code
- "インターフェースと抽象クラスには接頭辞も接尾辞も付けるべきではありません":https://blog.nette.org/en/prefixes-and-suffixes-do-not-belong-in-interface-names `Abstract`、`Interface`、`I` のようなものです


改行と波かっこ
=======

Nette のコーディング規約は PSR-12（または PER Coding Style）に沿っていますが、いくつかの点でそれを細かく定めたり変えたりしています。

- アロー関数はかっこの前に空白を入れずに書きます。つまり `fn($a) => $b` です
- 種類の違う `use` の import の文のあいだに空行は要りません
- 関数やメソッドの戻り値の型と、開く波かっこは、いつも別々の行に置きます。

```php
	public function find(
		string $dir,
		array $options,
	): array
	{
		// method body
	}
```

開く波かっこを別の行に置くのは、関数やメソッドの見出しを本体から目で分けるために大事です。見出しが 1 行なら区切りははっきりしています（左の図）。複数行なら、PSR では見出しと本体が溶け合ってしまいますが（真ん中）、Nette の規約では分かれたままです（右）。

[* new-line-after.webp *]


文書のかたまり（phpDoc）
===============

いちばんの決まりはこれです。**価値を足さずに**、パラメータの型や戻り値の型のような見出しの情報を**重ねて書かないこと**。

クラスの定義の文書のかたまりです。

- クラスの説明から始めます
- 続いて空行
- 続いて `@property`（あるいは `@property-read`、`@property-write`）のアノテーションを 1 行にひとつずつ。書き方は、アノテーション、空白、型、空白、`$name`
- 続いて `@method` のアノテーションを 1 行にひとつずつ。書き方は、アノテーション、空白、戻り値の型、空白、`name(type $param, ...)`
- `@author` のアノテーションは書きません。誰が書いたかはソースコードの履歴に残ります
- `@internal` や `@deprecated` のアノテーションは使えます

```php
/**
 * MIME message part.
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */
```

`@var` のアノテーションだけを含むプロパティの文書のかたまりは、1 行に書くべきです。

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

メソッドの定義の文書のかたまりです。

- メソッドの短い説明から始めます
- 空行は入れません
- `@param` のアノテーションを 1 行にひとつずつ
- `@return` のアノテーション
- `@throws` のアノテーションを 1 行にひとつずつ
- `@internal` や `@deprecated` のアノテーションは使えます

どのアノテーションのうしろにも空白をひとつ置きます。ただし `@param` だけは、読みやすさのために空白 2 つを置きます。

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


大域の関数と定数
========

大域の関数と定数は先頭のバックスラッシュなしで書きます。つまり `\count($arr)` ではなく `count($arr)` です。PHP が最適化できる関数には、コンパイラがより効率よく翻訳できるよう、ファイルの先頭に `use function` を足します。`count`、`strlen`、`is_array`、`is_string`、`is_scalar`、`sprintf` などの関数がそれに当たります。import のかたまりをこぢんまり保つために、関数は 1 行に並べます。

```php
use Nette;
use function count, is_array, is_scalar, sprintf;
```

ときには、その値を知ることがコンパイラの助けになる定数も import します。

```php
use const PHP_OS_FAMILY;
```


空白ではなくタブ
========

タブには空白に対していくつかの利点があります。

- 字下げの大きさをエディタでも "ウェブ":https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size でも変えられます
- 書き手の好みの字下げの大きさをコードに押し付けないので、コードが持ち運びやすくなります
- ひと打ちで入力できます（タブを空白に変えるエディタに限らず、どこでもです）
- 字下げこそがその役目です
- 目の不自由な仲間や見えない仲間の必要に応えます

プロジェクトでタブを使うことで幅を変えられるようにしています。多くの人には要らないことに見えるかもしれませんが、目の不自由な人には欠かせません。

点字ディスプレイを使う目の見えないプログラマーにとって、空白ひとつは点字のマスひとつです。ですから既定の字下げが空白 4 つなら、3 段めの字下げは、コードが始まる前に貴重な点字のマスを 12 個も無駄にします。ノートパソコンでもっともよくある 40 マスのディスプレイなら、それは使えるマスの 4 分の 1 以上を、何の情報も与えずに無駄にすることになります。


{{priority: -1}}