PSR-1(基本的なコーディング規約)の日本語訳と解説

前回に引き続きPSRの日本語訳と解説です。今回はPSR-1について。PSR-1は基本的なコーディング規約について定めています。

Basic Coding Standard:基本的なコーディング規約

[原文]

This section of the standard comprises what should be considered the standard coding elements that are required to ensure a high level of technical interoperability between shared PHP code.

[日本語訳]

このセクションの規約は、共有されるPHPのコードの相互運用性を保つために必要とされる標準的なコーディング要素を考慮し、構成されています。

「共有されるPHPのコード」というのは複数メンバーや複数の環境で共同で開発を行う際に、開発の対象となるPHPのコードのことです。

「high level of technical interoperability」はそのまま訳すと「技術的にレベルの高い相互運用性」となりますが、ちょっと分かりづらいなと思ったので、単に「相互運用性」としています。

[原文]

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119].

[日本語訳]

この文書に記載されているキーワード「しなければならない(MUST)」、「してはならない(MUST NOT)」、「必須(REQUIRED)」、「するものとする(SHALL)」、「しないものとする(SHALL NOT)」、「すべきである(SHOULD)」、「すべきでない(SHOULD NOT)」、「推奨する(RECOMMENDED)」、「することができる(MAY)」、「任意(OPTIONAL)」は、RFC 2119に記載されている内容で解釈されます。

ほぼ直訳そのままです、日本語訳にも誤訳や誤解のズレを防ぐ目的で「(MUST)」「(SHOULD)」というように、原文で補完しております。

1. Overview:概要

[原文]
  • Files MUST use only <?php and <?= tags.
  • Files MUST use only UTF-8 without BOM for PHP code.
  • Files SHOULD either declare symbols (classes, functions, constants, etc.) or cause side-effects (e.g. generate output, change .ini settings, etc.) but SHOULD NOT do both.
  • Namespaces and classes MUST follow an “autoloading” PSR: [PSR-0, PSR-4].
  • Class names MUST be declared in StudlyCaps.
  • Class constants MUST be declared in all upper case with underscore separators.
  • Method names MUST be declared in camelCase.
[日本語訳]
  • ファイルは<?phpタグと<?=タグのみ使用しなければなりません(MUST)。
  • ファイルはBOMなしUTF−8のみ使用しなければなりません(MUST)。
  • ファイルはシンボルの宣言(クラス・関数・定数など)または、副作用のある処理(出力の生成やiniの設定等)のどちらかであるべきです(SHOULD)。両方を含むべきではありません(SHOULD NOT)。
  • 名前空間とクラスはPSR: [PSR-0, PSR-4]「オートローディング」に準拠しなければなりません(MUST)。
  • クラス名はStudlyCapsで宣言しなければなりません(MUST)。
  • クラス定数はすべて大文字で、アンダースコアを区切り文字にしたもので宣言しなければなりません(MUST)。
  • 関数名はcamelCaseで宣言しなければなりません(MUST)。

StudlyCapsは単語の先頭の文字を大文字で表記する記法のことです。camelCaseは単語の先頭の文字を大文字で記載するが、最初の1文字目は小文字にする記法のことです。

概要ですので、詳細は次の項より説明されています。

2. Files:ファイル

2.1. PHP Tags:PHPタグ

[原文]

PHP code MUST use the long <?php ?> tags or the short-echo <?= ?> tags; it MUST NOT use the other tag variations.

[日本語訳]

PHPコードは<?php ?>タグか、出力の省略形式<?= ?>を使用しなければなりません(MUST)。 他のタグのバリエーションを使用してはいけません(MUST NOT)。

short_open_tagのオン・オフの設定にかかわらず動くように考慮されているものかと思われます。xml宣言の考慮の問題などから基本的にはshort_open_tagをオフにしておくのがベターですが、PHP5.3より以前のバージョンではshort_open_tagがオフだと<?= ?>が有効になりませんので注意が必要です。

2.2. Character Encoding:文字エンコーディング

[原文]

PHP code MUST use only UTF-8 without BOM.

[日本語訳]

PHPコードはBOMなしUTF−8のみ使用しなければなりません(MUST)。

なんかBOMに悩まされたのって、Windowsのメモ帳使ったときだけだった気がする。普通のIDE使ってれば特にBOMはつかないはず。

2.3. Side Effects:副作用

[原文]

A file SHOULD declare new symbols (classes, functions, constants, etc.) and cause no other side effects, or it SHOULD execute logic with side effects, but SHOULD NOT do both.

The phrase “side effects” means execution of logic not directly related to declaring classes, functions, constants, etc., merely from including the file.

“Side effects” include but are not limited to: generating output, explicit use of require or include, connecting to external services, modifying ini settings, emitting errors or exceptions, modifying global or static variables, reading from or writing to a file, and so on.

[日本語訳]

一つのファイルには、新しいシンボル(クラス・関数・定数等)の宣言と他の副作用を起こさないものか、副作用のあるロジックを行うか、どちらかであるべきで(SHOULD)、両方あるべきではありません(SHOULD NOT)。

「副作用」が意味するのは、クラス、関数、定数などの宣言に直接関係するものではなく、単にファイルをインクルードすることでロジックが実行されるものを指します。

「副作用」には、出力の生成・明示的なrequireもしくはincludeの使用・外部サービスへの接続・iniの設定の変更・エラーまたは例外の発行・グローバル変数または静的変数の変更・ファイルへの読み書き等々が含まれますが、これだけというわけではありません。

副作用は「クラス・関数・定数の宣言以外」と覚えておいて、ほぼ間違いは無いかと思います。具体的には下記例がわかりやすいですね。

[原文]

The following is an example of a file with both declarations and side effects; i.e, an example of what to avoid:

<?php
// side effect: change ini settings
ini_set('error_reporting', E_ALL);

// side effect: loads a file
include "file.php";

// side effect: generates output
echo "<html>\n";

// declaration
function foo()
{
    // function body
}
[日本語訳]

下記は宣言と副作用の両方を持つファイルの例です。(つまり悪い例)

<?php
// 副作用: iniの設定変更
ini_set('error_reporting', E_ALL);

// 副作用: ファイルの読み込み
include "file.php";

// 副作用: 出力の生成
echo "<html>\n";

// 宣言
function foo()
{
    // 関数の処理
}

`ini_set`とか`include`は宣言のファイルと混ぜがちなので注意が必要ですね。

[原文]

The following example is of a file that contains declarations without side effects; i.e., an example of what to emulate:

<?php
// declaration
function foo()
{
    // function body
}

// conditional declaration is *not* a side effect
if (! function_exists('bar')) {
    function bar()
    {
        // function body
    }
}
[日本語訳]

下記は副作用のない、宣言が含まれるファイルの例です。(つまり良い例)

<?php
// 宣言
function foo()
{
    // 関数の処理
}

// 条件付き宣言は副作用ではありません
if (! function_exists('bar')) {
    function bar()
    {
        // 関数の処理
    }
}

条件付き宣言は副作用出ないところに注意しましょう。

「an example of what to avoid:」「an example of what to emulate:」はそれぞれ「避ける例」「見習う例」という意味ですが、単純に「悪い例」「良い例」と訳しました。

3. Namespace and Class Names:名前空間・クラス名

[原文]

Namespaces and classes MUST follow an “autoloading” PSR: [PSR-0, PSR-4].

This means each class is in a file by itself, and is in a namespace of at least one level: a top-level vendor name.

Class names MUST be declared in StudlyCaps.

Code written for PHP 5.3 and after MUST use formal namespaces.

[日本語訳]

名前空間とクラスはPSR: [PSR-0, PSR-4]「オートローディング」に準拠しなければなりません(MUST)。

これは各クラスが単独でファイルに存在し、トップレベルがベンダー名の少なくとも1つ以上の名前空間にあることを意味します。

クラス名はStudlyCapsで宣言しなければなりません(MUST)。

PHP5.3以降で書かれたコードは、正式な名前空間を使用しなければなりません(MUST)。

PSR-0は廃止予定なので、今後はPSR-4を気にしておけばいいかと。要はオートローディング規格はオートローダーのためのクラスの命名規則なので、それに従わざるを得ないということです。

[原文]

For example:

<?php
// PHP 5.3 and later:
namespace Vendor\Model;

class Foo
{
}

Code written for 5.2.x and before SHOULD use the pseudo-namespacing convention of `Vendor_` prefixes on class names.

// PHP 5.2.x and earlier:
class Vendor_Model_Foo
{
}
[日本語訳]

例:

<?php
// PHP5.3以降:
namespace Vendor\Model;

class Foo
{
}

PHP5.2.x以前に書かれたコードは、クラス名にVendor_接頭語の疑似名前空間規則を使用するべきです(SHOULD)。

<?php
// PHP 5.2.x and earlier:
class Vendor_Model_Foo
{
}

名前空間が使用できるのはPHP5.3からなので、5.2.x以前のものは疑似名前空間を使用しなければオートローディングの恩恵を受けれません。Vendor_接頭語と明記してますが、ベンダー名なので、任意の名前で大丈夫です。

ちなみにPSR-4ではアンダーバーは特にディレクトリの区切り文字として扱わない事になっています。

4. Class Constants, Properties, and Methods:クラス定数・プロパティ・メソッド

[原文]

The term “class” refers to all classes, interfaces, and traits.

[日本語訳]

「クラス」という用語はすべてのクラス、インターフェース、そしてトレイトを指します。

つまり、この章での説明はインターフェースもトレイトも含まれるということになります。

4.1. Constants:定数

[原文]

Class constants MUST be declared in all upper case with underscore separators.

For example:

<?php
namespace Vendor\Model;

class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '2012-06-01';
}
[日本語訳]

クラス定数はすべて大文字で、アンダースコアを区切り文字にしたもので宣言しなければならなりません(MUST)。

例:

<?php
namespace Vendor\Model;

class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '2012-06-01';
}

4.2. Properties:プロパティ

[原文]

This guide intentionally avoids any recommendation regarding the use of $StudlyCaps, $camelCase, or $under_score property names.

Whatever naming convention is used SHOULD be applied consistently within a reasonable scope. That scope may be vendor-level, package-level, class-level, or method-level.

[日本語訳]

本規約はプロパティ名に関しての命名規則は特に推奨するものはなく、$StudlyCaps$camelCase$under_scoreのいずれを使用しても構いません。

しかし、命名規則は適正な範囲で一貫して使用されるべきです(SHOULD)。その範囲は、ベンダーレベル、パッケージレベル、クラスレベル、またはメソッドレベルのいずれかです。

「いずれを使用しても構いません」と訳しましたが、原文には「意図的に推奨することを避ける」としか書いていません。しかしまあ、そ言う言うことになります。

プロパティの命名規則なのに一貫性の範囲にメソッドが含まれるのがよくわかりませんが、まあ、メソッド内の変数クラス内で一貫しているべきだと考えて置くことにします。

4.3. Methods:メソッド

[原文]

Method names MUST be declared in camelCase().

[日本語訳]

メソッド名はcamelCase()で宣言しなければなりません(MUST)。

メソッド名はcamelCaseで統一しましょう。

コメントを残す