Help:Extension:Translate/開発者向けガイド

This page is a translated version of the page Help:Extension:Translate/Developer guide and the translation is 100% complete.

Translate 拡張機能は、数百のクラスからなる大規模な拡張機能です。このページでは、コードに手を加える開発者のためのガイダンスを提供します。このページとリンク先の文書を読めば、Translate のコードがどのように構成され、どのような特別な規約が使用されているか、よりよく理解できるはずです。一般的な MediaWiki の開発方針、コーディング規約、Gerrit や Phabricator のようなツールの使い方は範囲外です。これらの話題は既にご存知だと思いますが、Translate に適用される場合、ここでは繰り返しません。

Translate 拡張機能では、多くの大規模な移行が同時に進行しています。ここでは、現在進行中の主な移行を列挙し、新しいコードにどのスタイルが好ましいかを詳しく説明します。一般に、既存のコードを修正する場合は、現在のスタイルを維持し、移行は別に行うのがいいでしょう。コードを触るときにやってもいい小さなクリーンアップもあります。

名前空間の移行

現在、すべての Translate のコードを名前空間 \MediaWiki\Extension\Translate 配下に移行しているところです。すべての名前空間付きコードは、src/ ディレクトリ配下に置かれます。新しい PHP ファイルは、すべて適切な名前空間に配置する必要があります。どの名前空間が利用できるようになるかのガイダンスは Extension:Translate/Namespaces を参照してください。名前空間は、機能ではなくドメインで整理されています。名前空間やクラス名では省略形を避けるべきです。レガシーコードは、リポジトリのルート (root) とさまざまな下位ディレクトリにあります。

Gerrit では、SonarCube は src/ ディレクトリ配下のコードのみを対象としてコードレビューカバレッジを計算します。

テストを統合テストと単体テストに分割

以前は、統合テストと単体テストの区別はありませんでした。新しいコードの場合、単体テストが主なテストの種類になるはずです。単体テストは、tests/phpunit/unit ディレクトリ配下の名前空間のレイアウトに合わせたディレクトリに配置されます。そのディレクトリの中に Makefile があり、開発中に単体テストの全部または一部を簡単に実行できます。

型宣言とコメント

すべての新しいコードは、パラメーターと戻り値の両方の型を宣言する必要があります。また、厳密な型付け (strict_types) を declare( strict_types = 1 ); で有効にする必要があります。

型宣言のおかげで、ほとんどの関数やメソッドのコメントは、パラメーター名と型を繰り返すだけで、冗長になっています。このコードでは、付加価値を提供する場合以外は冗長な説明文書を追加しないでください。そのような例として、配列型に対してより正確な型ヒントを提供することが挙げられます。例:

class UserManager {
  /** @return User[] */
  public function getAllUsers(): array { ... }
}

上記のように、1 つのタグや 1 行の記述しかないコメントには、1 行コメント構文も使用します。

戻り値の型宣言の : 付近の空白類に関する linter はありません。そのような標準ができるまでは、上記のように「前に空白なし、後に空白 1 つ」というスタイルを使用してください。

コンストラクターの依存性注入

新しいコードには、その依存性をすべてコンストラクターで注入する必要があります。一部の場合はまだ実行不可能で、原因は ObjectFactory のサポートがジョブや管理スクリプトなどの特定の種のクラスに未対応なためです。このような新しいコードでは、将来コンストラクターの依存性注入に移行しやすいように、すべての依存性をクラスのコンストラクター (またはクラスへの主なエントリポイント) に配置します。

メンテナンススクリプトでは、PHP の自動ローダーを必要とするコードは使用できません。従って、すべての依存性はコンストラクターではなく execute メソッドでのみ宣言できます。

ファイルのヘッダー

新しいコードには、以下のような最小限のヘッダーを採用しています:

<?php
declare( strict_types = 1 );

namespace Example;

use OtherStuff;

/**
 * Class description.
 * @author Your name
 * @license GPL-2.0-or-later
 * @since 2020.06
 */
class ExampleClass {
  /** @return User[] */
  public function getAllUsers(): array { ... }
}

著作権をより明確に主張したい場合は、必要に応じて @copyright タグを追加することもできます。

宣言とバージョン番号

後方互換性のない方法で Translate のコードを変更する場合、コードのすべての使用箇所に対して https://codesearch.wmcloud.org/search/ をチェックしてください。既知の使用箇所は、TwnMainPage、TranslateSVG、CentralNotice、MassMessage と translatewiki リポジトリにある多数のものです。

@deprecated タグと wfDeprecated() ハード廃止予定 (hard deprecation) を含む、MediaWiki コアによって提供される廃止予定の機能を使用できます。コードの既知の使用箇所がない場合、安定版として明示的にマークされていない限り、廃止予定にせずに後方互換性のない方法で変更しても問題ありません (安定版インターフェイスポリシーを参照してください)。安定版としてマークされたコードは、少なくとも 1 回の MediaWiki 言語拡張バンドル (MLEB) リリースではハード廃止予定 (hard-deprecated) とすべきです。

MediaWiki コアのバージョン番号は Translate の文脈では無意味です。Translate は常に複数の MediaWiki リリースをサポートしているからです。 Translate 自体は (MLEBの一部として) YYYY.MM スタイルのバージョン付けを使用しています。新しいクラスとメソッドには、@since YYYY.MM タグを付ける必要があります。