Skip to content

Y
yii2
Commit beacdf65 by Alexander Makarov
Options

Merge pull request #6994 from softark/docs-internals-ja-reviewed

Docs internals ja reviewed [ci skip]
parents de28c1c5 82857d3e
Showing with 52 additions and 67 deletions
docs/internals-ja/automation.md
......@@ -4,12 +4,12 @@
Yii の開発に取り組む際に、自動化できるタスクがいくつかあります:
- フレームワークのルートディレクトリに配置されるクラスマップ `classes.php` の生成。
`./build/build classmap` を走らせて生成してください。
`./build/build classmap` を実行して生成してください。
- クラスファイルの中の、ゲッターとセッターによって導入されるプロパティを記述する `@property` 注釈の生成。
`./build/build php-doc/property` を走らせて注釈を更新してください。
`./build/build php-doc/property` を実行して注釈を更新してください。
- コードスタイルと phpdoc コメントの些細な問題の修正。
`./build/build php-doc/fix` を走らせて修正してください。
`./build/build php-doc/fix` を実行して修正してください。
このコマンドは完璧なものではないため、望ましくない変更があるかもしれませんので、コミットする前に変更点をチェックしてください。
`git add -p` を使って変更をプレビューすることも出来ます。
`git add -p` を使って変更をレビューすることが出来ます。
docs/internals-ja/core-code-style.md
......@@ -52,7 +52,7 @@ PHP 繧ｳ繝ｼ繝峨 BOM 辟｡縺励 UTF-8 縺ｮ縺ｿ繧剃ｽｿ繧上↑縺代ｌ縺ｰ縺ｪ繧翫∪縺帙ｓ
- クラスは `CamelCase` で命名されなければなりません。
- 中括弧は常にクラス名の下の行に書かれるべきです。
- 全てのクラスは PHPDoc に従ったドキュメントブロックを持たなければなりません。
- クラス内のすべてのコードは単一のタブによってインデントされなければなりません。
- クラス内のすべてのコードは一個のタブによってインデントされなければなりません。
- 一つの PHP ファイルにはクラスが一つだけあるべきです。
- 全てのクラスは名前空間に属すべきです。
- クラス名はファイル名と合致すべきです。クラスの名前空間はディレクトリ構造と合致すべきです。
......@@ -107,7 +107,6 @@ class Foo
### 4.3. メソッド
- 関数およびメソッドは、先頭を小文字にした `camelCase` で名付けるべきです。
Functions and methods should be named using `camelCase` with first letter lowercase.
- 名前は、関数の目的を示す自己説明的なものであるべきです。
- クラスのメソッドは常に修飾子 `private`、`protected` または `public` を使って、可視性を宣言すべきです。`var` は許可されません。
- 関数の開始の中括弧は関数宣言の次の行に置くべきです。
......@@ -145,16 +144,7 @@ class Foo
- PHP の全ての型と値には小文字を使うべきです。このことは、`true`、`false`、`null` および `array` にも当てはまります。
連想配列に対しては次の書式を使います:
```php
$config = [
'name' => 'Yii',
'options' => ['usePHP' => true],
];
```
既存の変数の型を変えることは悪い慣行であると見なされます。本当に必要でない限り、そのようなコードを書かないように努めましょう。
既存の変数の型を変えることは悪いプラクティスであると見なされています。本当に必要でない限り、そのようなコードを書かないように努めましょう。
```php
......@@ -170,7 +160,7 @@ public function save(Transaction $transaction, $argument2 = 100)
- 文字列が変数および一重引用符を含まない場合は、一重引用符を使います。
```php
$str = 'Like this.';
$str = 'こんな具合に。';
```
- 文字列が一重引用符を含む場合は、余計なエスケープを避けるために二重引用符を使ってもかまいません。
......@@ -178,25 +168,25 @@ $str = 'Like this.';
#### 変数置換
```php
$str1 = "Hello $username!";
$str2 = "Hello {$username}!";
$str1 = "こんにちは $username さん";
$str2 = "こんにちは {$username} さん";
```
下記は許可されません:
下記は許可されません。
```php
$str3 = "Hello ${username}!";
$str3 = "こんにちは ${username} さん";
```
#### 連結
文字列を連結するときは、ドットの周囲に空白を追加します:
文字列を連結するときは、ドットの前後に空白を追加します。
```php
$name = 'Yii' . ' Framework';
```
文字列が長い場合、書式は以下のようにします:
文字列が長い場合、書式は以下のようにします。
```php
$sql = "SELECT *"
......@@ -212,13 +202,13 @@ $sql = "SELECT *"
- 負の数を配列のインデックスに使わないこと。
配列を宣言するときは、下記の書式を使います:
配列を宣言するときは、下記の書式を使います。
```php
$arr = [3, 14, 15, 'Yii', 'Framework'];
```
一つの行には多過ぎるほど要素がたくさんある場合は:
一つの行には多過ぎるほど要素がたくさんある場合は、
```php
$arr = [
......@@ -230,7 +220,7 @@ $arr = [
#### 連想配列
連想配列には下記の書式を使います:
連想配列には下記の書式を使います。
```php
$config = [
......@@ -250,13 +240,14 @@ $config = [
```php
if ($event === null) {
return new Event();
} elseif ($event instanceof CoolEvent) {
}
if ($event instanceof CoolEvent) {
return $event->instance();
} else {
return null;
}
return null;
// 下記は許容されません:
// 下記は許容されません
if (!$model && null === $event)
throw new Exception('test');
```
......@@ -345,14 +336,11 @@ $mul = array_reduce($numbers, function($r, $x) use($n) {
- ドキュメントの文法については [phpDoc](http://phpdoc.org/) を参照してください。
- ドキュメントの無いコードは許容されません。
- 全てのクラスファイルは、ファイルレベルの doc ブロックを各ファイルの先頭に持ち、
クラスレベルの doc ブロックを各クラスの直前に持たなければなりません。
- 全てのクラスファイルは、ファイルレベルの doc ブロックを各ファイルの先頭に持ち、クラスレベルの doc ブロックを各クラスの直前に持たなければなりません。
- メソッドが実際に何も返さないときは `@return` を使う必要はありません。
- `yii\base\Object` から派生するクラスのすべての仮想プロパティは、クラスの doc ブロックで `@property` タグでドキュメントされます。
これらの注釈は、`build` ディレクトリで `./build php-doc` コマンドを走らせることにより、
対応する getter や setter の `@return` や `@param` タグから自動的に生成されます。
getter や setter に `@property` タグを追加することによって、
これらのメソッドによって導入されるプロパティに対してドキュメントのメッセージを明示的に与えることが出来ます。
これらの注釈は、`build` ディレクトリで `./build php-doc` コマンドを走らせることにより、対応する getter や setter の `@return` や `@param` タグから自動的に生成されます。
getter や setter に `@property` タグを追加することによって、これらのメソッドによって導入されるプロパティに対してドキュメントのメッセージを明示的に与えることが出来ます。
これは `@return` で記述されているのとは違う説明を与えたい場合に有用です。
下記が一例です。
......@@ -370,8 +358,7 @@ $mul = array_reduce($numbers, function($r, $x) use($n) {
public function getErrors($attribute = null)
```
>Note|注意: ここでは読みやすさを考慮してドキュメントの内容を日本語に翻訳していますが、
コアコードや公式エクステンションに対して寄稿する場合は、当然ながら、コメントには英語だけを使う必要があるでしよう。
>Note|注意: ここでは読みやすさを考慮してドキュメントの内容を日本語に翻訳していますが、コアコードや公式エクステンションに対して寄稿する場合は、当然ながら、コメントには英語だけを使う必要があります。
#### ファイル
......@@ -427,7 +414,7 @@ public function getEventHandlers($name)
#### Markdown
上記の例に見られるように、phpDoc コメントの書式設定には markdown を使っています。
上記の例に見られるように、phpDoc コメントの書式設定には markdown を使います。
ドキュメントの中でクラス、メソッド、プロパティをクロスリンクするために使える追加の文法があります。
......@@ -444,7 +431,7 @@ public function getEventHandlers($name)
`|` の前の部分がメソッド、プロパティ、クラスへの参照であり、`|` の後ろの部分がリンクのラベルです。
下記の文法を使ってガイドにリンクすることも可能です:
下記の文法を使ってガイドにリンクすることも可能です。
```markdown
[ガイドへのリンク](guide:file-name.md)
......@@ -470,7 +457,7 @@ public function getEventHandlers($name)
### `self` 対 `static`
以下の場合を除いて、常に `static` を使います:
以下の場合を除いて、常に `static` を使います。
- 定数へのアクセスには `self` を使わなければなりません: `self::MY_CONSTANT`
- private な静的プロパティへのアクセスには `self` を使わなければなりません: `self::$_events`
......
docs/internals-ja/design-decisions.md
......@@ -12,9 +12,9 @@
技術者でないエンドユーザに対して表示され、また、そういうユーザに対して意味を持つメッセージは翻訳されるべきである。
HTTP ステータスメッセージ、コードに関する例外などは翻訳されるべきではない。
コンソールメッセージは、エンコーディングとコードページの処理に困難が伴うため、常に英語で表示されるものとする。
3. **[Auth クライアントのサポートの追加](https://github.com/yiisoft/yii2/issues/1652)**
保守性を高めるために、コアエクステンションに Auth クライアントをこれ以上追加しない。
Auth クライアントの追加はユーザエクステンションの形でなされるべきである。
3. **[認証クライアントのサポートの追加](https://github.com/yiisoft/yii2/issues/1652)**
保守性を高めるために、コアエクステンションには認証クライアントをこれ以上追加しない。
認証クライアントの追加はユーザエクステンションの形でなされるべきである。
4. **クロージャを使うときは**、たとえ使用されないものがある場合でも、**渡されたすべてのパラメータをシグニチャに含める** ことが推奨される。
このようにすると、全ての情報が直接に見えるので、コードの修正やコピーがより容易になり、どのパラメータが実際に利用できるかをドキュメントで調べる必要がなくなる。
([#6584](https://github.com/yiisoft/yii2/pull/6584), [#6875](https://github.com/yiisoft/yii2/issues/6875))
docs/internals-ja/getting-started.md
......@@ -12,22 +12,21 @@ Yii2 の開発を始めよう
このコマンドは内部的に `composer update` を実行します。
5. 以上で、Yii 2 をハックするための作業用環境が手に入りました。
最新の変更を pull するために yii2 の upstream レポジトリを追加することも出来ます。
最新の変更を pull するために yii2 の upstream レポジトリを追加することが出来ます。
```
git remote add upstream https://github.com/yiisoft/yii2.git
```
プルリクエストの作成に関する詳細は、[Yii 2 寄稿者のための Git ワークフロー
](git-workflow.md) を参照してください。
プルリクエストの作成に関する詳細は、[Yii 2 寄稿者のための Git ワークフロー](git-workflow.md) を参照してください。
ユニットテスト
--------------
単体テスト
----------
ユニットテストを走らせるためには、dev-repo のための composer パッケージをインストールする必要があります。
単体テストを走らせるためには、dev-repo のための composer パッケージをインストールする必要があります。
`composer update` をレポジトリのルートディレクトリで実行して、最新のパッケージを取得してください。
そうすれば、`phpunit` を走らせてユニットテストを実行することが出来ます。
そうすれば、`phpunit` を走らせて単体テストを実行することが出来ます。
テストを現在取り組んでいる一群のテストだけに制限することが出来ます。
例えば、バリデータと redis のためだけにテストを実行するには、`phpunit --group=validators,redis` とします。
......
docs/internals-ja/git-workflow.md
Yii 2 寄稿者のための Git ワークフロー
=====================================
Yii の開発に寄稿したい、ですって? すばらしい! けれども、あなたの修正案が速やかに採用されるチャンスを増やすためには、
以下のステップを踏むようにしてください (最初の二つのステップは最初に寄稿するときにだけ必要になります)。
あなたが git と github については初めてだという場合は、最初に [github help](http://help.github.com/) や [try git](https://try.github.com) を精査したり、
[git internal data model](http://nfarina.com/post/9868516270/git-is-simpler) についていくらか学習したりする必要があるかもしれません。
Yii の開発に寄稿したい、ですって? すばらしい!
けれども、あなたの修正案が速やかに採用されるチャンスを増やすためには、以下のステップを踏むようにしてください (最初の二つのステップは最初に寄稿するときにだけ必要になります)。
あなたが git と github については初めてだという場合は、最初に [github help](http://help.github.com/) や [try git](https://try.github.com) を精査したり、[git internal data model](http://nfarina.com/post/9868516270/git-is-simpler) についていくらか学習したりする必要があるかもしれません。
### 1. github で Yii リポジトリを [Fork](http://help.github.com/fork-a-repo/) し、あなたのフォークをあなたの開発環境にクローンする
......@@ -12,26 +11,27 @@ Yii の開発に寄稿したい、ですって? すばらしい! けれども、
git clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git
```
Linux において、GitHub で GIT を設定するのに問題が生じたり、"Permission Denied (publickey)" のようなエラーが発生したりする場合は、
[setup your GIT installation to work with GitHub](http://help.github.com/linux-set-up-git/) に従ってください。
Linux において、GitHub で GIT を設定するのに問題が生じたり、"Permission Denied (publickey)" のようなエラーが発生したりする場合は、[setup your GIT installation to work with GitHub](http://help.github.com/linux-set-up-git/) に従ってください。
### 2. メインの Yii リポジトリを "upstream" という名前でリモートとして追加する
Yii をクローンしたディレクトリ、通常は "yii2" に入ります。そして、以下のコマンドを打ち込みます:
Yii をクローンしたディレクトリ、通常は "yii2" に入って、以下のコマンドを打ち込みます。
```
git remote add upstream git://github.com/yiisoft/yii2.git
```
### 3. あなたが取り組んでいる問題が、修正するために著しい努力を要求するものである場合は、それに対する課題(issue)が作成されていることを確認する
### 3. あなたが取り組んでいる問題が、修正するために著しい努力を要求するものである場合は、それに対する課題 (issue) が作成されていることを確認する
全ての新機能とバグ修正は、議論とドキュメントのための単一の参照ポイントを提供するために、それに結びつく課題を持つべきです。
全ての新機能とバグ修正は、議論とドキュメントのための単一の参照ポイントを提供するために、それに結びつく課題 (issue) を持つべきです。
数分間時間を取って、既存の課題リストに目を通し、あなたが寄稿しようとしている問題に合致するものが無いかどうか調べてください。
もし課題リストにすでに挙っているのを見つけた場合は、その課題にコメントを残して、あなたがその項目について取り組もうとしていることを示してください。
あなたが取り組もうとしている問題に合致する既存の課題が見つからなかった場合は、新しい課題を作成してください。単純な修正であれば、直接にプルリクエストをしてください。
あなたが取り組もうとしている問題に合致する既存の課題が見つからなかった場合は、新しい課題を作成してください。
単純な修正であれば、直接にプルリクエストをしてください。
こうすることで、開発チームはあなたの提案をレビューし、将来にわたって適切なフィードバックを提供することが可能になります。
> 小さな変更や、ドキュメントの問題、または単純な修正については、課題を作成する必要はありません。それらについては、プルリクエストだけで十分です。
> 小さな変更や、ドキュメントの問題、または単純な修正については、課題を作成する必要はありません。
それらについては、プルリクエストだけで十分です。
### 4. メインの Yii ブランチから最新のコードをフェッチする
......@@ -59,8 +59,8 @@ git checkout -b 999-name-of-your-branch-goes-here
動くことを確認してくださいね :)
ユニットテストは常に歓迎されます。テストされ、十分にカバーされたコードは、あなたの寄稿をチェックするタスクを非常に単純化してくれます。
ユニットテストの失敗を中身とする課題を立てることも許容されています。
単体テストは常に歓迎されます。テストされ、十分にカバーされたコードは、あなたの寄稿をチェックするタスクを非常に単純化してくれます。
単体テストの失敗を中身とする課題を立てることも許容されています。
### 7. CHANGELOG を更新する
......@@ -143,8 +143,7 @@ git push origin --delete 999-name-of-your-branch-goes-here
### 注意:
退行 (regression) を早期に発見するために、github 上の Yii コードベースへのマージは、すべて [Travis CI](http://travis-ci.org) に取り上げられて、自動化されたテストにかけられます。
コアチームとしては、このサービスに過大な負担をかけたくないために、
以下の場合にはマージの説明に [`[ci skip]`](http://about.travis-ci.org/docs/user/how-to-skip-a-build/) が含まれるようにしてください。
コアチームとしては、このサービスに過大な負担をかけたくないために、以下の場合にはマージの説明に [`[ci skip]`](http://about.travis-ci.org/docs/user/how-to-skip-a-build/) が含まれるようにしてください。
すなわち、プルリクエストが、
* javascript、css または画像ファイルだけに影響する場合
......
docs/internals-ja/view-code-style.md
......@@ -25,7 +25,7 @@ use yii\widgets\ActiveForm;
// コンテキストのプロパティを設定したり、コンテキストのセッターを呼んだり、その他のことをする。
$this->title = 'Posts';
?>
<!-- foreach、for などには、独立した PHP ブロックを使う方が良い -->
<!-- foreach、for, if などには、独立した PHP ブロックを使う方が良い -->
<?php foreach ($posts as $post): ?>
<!-- インデントのレベルに注目 -->
<h2><?= Html::encode($post['title']) ?></h2>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment