コーディング規約

このドキュメントでは、Nette開発のためのルールと推奨事項について説明します。Netteにコードを貢献する際には、これらを遵守する必要があります。最も簡単な方法は、既存のコードを模倣することです。 目標は、すべてのコードが一人の人間によって書かれたかのように見えるようにすることです。

Netteコーディング規約は、PSR-12 Extended Coding Style に準拠していますが、2つの主な例外があります：インデントには スペースの代わりにタブ を使用し、クラス定数にPascalCaseを使用 します。

一般規則

  • 各PHPファイルには declare(strict_types=1) を含める必要があります
  • 読みやすさ向上のため、メソッドを区切るために2つの空行を使用します。
  • シャットアップ演算子を使用する理由は文書化する必要があります：@mkdir($dir); // @ - ディレクトリは存在する可能性があります。
  • 弱い型付けの比較演算子（例：==, !=, …）を使用する場合、意図を文書化する必要があります：// == nullを受け入れる
  • 複数の例外を1つの exceptions.php ファイルに記述できます。
  • インターフェースではメソッドの可視性を指定しません。常にpublicだからです。
  • 各プロパティ、戻り値、パラメータには型を指定する必要があります。逆に、final定数には型を記述しません。明らかだからです。
  • 文字列リテラル自体にアポストロフィが含まれていない限り、文字列を囲むには単一引用符を使用する必要があります。

命名規則

折り返しと波括弧

Netteコーディング規約はPSR-12（またはPER Coding Style）に準拠しており、いくつかの点で補足または変更されています：

  • アロー関数は括弧の前にスペースを入れずに記述します。つまり fn($a) => $b
  • 異なるタイプの use インポートステートメントの間に空行は必要ありません
  • 関数/メソッドの戻り値の型と開始波括弧は常に別々の行に記述します：
	public function find(
		string $dir,
		array $options,
	): array
	{
		// メソッド本体
	}

開始波括弧を別々の行に置くことは、関数/メソッドのシグネチャと本体を視覚的に区別するために重要です。シグネチャが1行の場合、区別は明確です（左の画像）。複数行の場合、PSRではシグネチャと本体が混ざり合いますが（中央）、Nette標準では引き続き区別されます（右）：

ドキュメンテーションブロック (phpDoc)

主なルール：付加価値なしに、パラメータの型や戻り値の型など、シグネチャ内の情報を決して複製しないでください。

クラス定義のドキュメンテーションブロック：

  • クラスの説明で始まります。
  • 空行が続きます。
  • @property （または @property-read, @property-write）アノテーションが続きます。構文は：アノテーション、スペース、型、スペース、$名前。
  • @method アノテーションが続きます。構文は：アノテーション、スペース、戻り値の型、スペース、名前(型 $param, …)。
  • @author アノテーションは省略されます。作者情報はソースコードの履歴に保存されます。
  • @internal または @deprecated アノテーションを使用できます。
/**
 * MIMEメッセージパート。
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */

@var アノテーションのみを含むプロパティのドキュメンテーションブロックは、1行であるべきです：

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

メソッド定義のドキュメンテーションブロック：

  • メソッドの簡単な説明で始まります。
  • 空行はありません。
  • @param アノテーションは個別の行に記述します。
  • @return アノテーション。
  • @throws アノテーションは個別の行に記述します。
  • @internal または @deprecated アノテーションを使用できます。

各アノテーションの後には1つのスペースが続きますが、@param の後には読みやすさ向上のために2つのスペースが続きます。

/**
 * ディレクトリ内のファイルを検索します。
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array

スペースの代わりにタブ

タブはスペースに比べていくつかの利点があります：

  • インデントのサイズはエディタや ウェブ で調整できます
  • ユーザーのインデントサイズの好みをコードに強制しないため、コードの移植性が向上します
  • 1回のキーストロークで入力できます（タブをスペースに変換するエディタだけでなく、どこでも）
  • インデントはその目的です
  • 視覚障害のある同僚や盲目の同僚のニーズを尊重します

私たちのプロジェクトでタブを使用することにより、幅のカスタマイズが可能になります。これはほとんどの人にとっては不要に見えるかもしれませんが、視覚障害のある人々にとっては不可欠です。

点字ディスプレイを使用する盲目のプログラマにとって、各スペースは1つの点字セルを表します。したがって、デフォルトのインデントが4スペースの場合、第3レベルのインデントはコードが始まる前に12個の貴重な点字セルを浪費します。 ノートパソコンで最も一般的に使用される40セルのディスプレイでは、利用可能なセルの4分の1以上が情報なしで浪費されます。

  1. ドキュメンテーション
  2. Netteの貢献者になる
  3. コーディング規約