Help:Extension:Translate/Developer guide/ja

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

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

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

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

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

型宣言のおかげで、ほとんどの関数やメソッドのコメントは、パラメーター名と型を繰り返すだけで、冗長になっています. このため、パラメーターや戻り値の型宣言の欠落に対する linter チェックは、型宣言を使用する場所とほぼ一致する  および   の配下のコードでは無効になっています. このコードでは、付加価値を提供する場合以外は冗長な説明文書を追加しないでください. そのような例として、配列型に対してより正確な型ヒントを提供することが挙げられます. 例:

As illustrated above, for comments having only one tag or one line description, do use the one line comment syntax as well.

Constructor dependency injection
New code should have all its dependencies injected via constructor. In many cases this is not yet possible, due to many services only being available in MediaWiki 1.35 (we currently support 1.34 and later) as well lack of ObjectFactory support for services. For such new code, place all dependencies on the class constructor (or main entry point to the class) to easy migration to constructor dependency injection in the future.

File header
For new code, we have chosen the following minimalistic header:

If you wish to assert your copyright more explicitly, you can optionally add @copyright tag as well.

Deprecation and version numbers
When changing Translate code in backwards incompatible ways, do check https://codesearch.wmflabs.org/search/ for any users of the code. Known users are TwnMainPage, TranslateSVG, CentralNotice, MassMessage and bunch of stuff in the translatewiki repo.

You can use the deprecation facilities provided by MediaWiki core, including the @deprecated tag and wfDeprecated hard deprecation. If there are no known users of the code, it is okay to change it in backwards incompatible way without deprecation, unless it is explicitly marked as stable (See Stable interface policy). Code marked as stable should be hard-deprecated at least for one MLEB release.

MediaWiki core version numbers are meaningless in the context of Translate, as Translate always supports multiple MediaWiki releases. Translate itself uses YYYY.MM style versioning (as part of MLEB). New classes and methods should be annotated with @since YYYY.MM tags.