Manual:Coding conventions/ja

このページでは、MediaWiki コードベース内や、ウィキメディアのウェブサイト群で使用されることを意図している拡張機能内で使用される、コーディング規約を説明します. コードレビューワーは、これら規約に従わない変更をまとめて-1処理することがあります. その場合は、スタイルの問題を修正してパッチを更新するように推奨されたと解釈するようにお願いします.

このページでは、コードがどの言語で書かれているかにかかわらずすべての MediaWiki コードに適用される全般的な規約を列挙します. MediaWiki の特定のコンポーネントやファイルの種類に適用されるガイドラインについては、以下を参照してください:


 * SVG
 * SVG

wiki技術部 (少なくとも運営/パペットに適用):


 * Puppet

タブの幅
各行は深さ1段ごとにタブ記号1個でインデントを施します. タブ1個が何文字相当か自分で決めることはできません. MediaWikiの開発者の多くは可読性の面からもタブ1個を半角アキ4個相当が妥当だとしていますが、多くのシステムでは半角アキ8個相当の設定で、なかには半角アキ2個のつもりで使用する開発者もいます.

テキストエディタのvim利用者には$HOME/.vimrcに以下の記述を追加して設定する方法があります.

autocmd Filetype php setlocal ts=4 sw=4

CSSやHTML、JavaScriptにも似た記述を使います.

しかしながらPythonでは、コードのスタイルガイドPEP 8の空白スペース (アキ) ガイドラインに従い、タブではなくアキを使用するように推奨しています.

改行
どのファイルも改行はUnix式にします (LF記号1個であって、CR+LFではない).


 * Windows版のgitでは (既定として) コミットの段階で自動的にCR+LF改行をLFに置換します.

すべてのファイルについて、末尾に改行文字を付けるべきです.


 * その他の行はすべて、行末に改行記号があるため整合性があります.
 * これにより非バイナリ形式 (差分など) でのデータ取り回しが楽になります.
 * catやwcなどコマンドラインツールで欠如するとファイル処理が円滑に進みません (あるいは少なくとも予期したりこうあるべきと思う挙動になりません).

エンコーディング
テキストファイルはすべてBOMのない、UTF-8で符号化.

ファイル編集には、必ずBOMを挿入するMicrosoft Notepadは使用できません. ファイル冒頭に特殊文字BOMが入ることによって、ウェブブラウザがそれをクライアントに出力するため、PHPファイルの作動が阻害されます.

まとめるなら、必ずUTF-8対応でBOMを挿入しないエディタをご利用ください.

末尾の空白類
IDEを使用すると「Home」と「End」のキー (その他のキーボードショートカットも含む) を押すと、想定どおり、通常は行末の空白スペースを無視してコード末尾にジャンプします. ところが非IDEテキストエディタの場合は「End」キーを押すと行末の空白スペースの末尾に飛んでしまい、開発者は入力しようとして想定した位置まで、バックスペースで戻る必要があります.

操作としては、行末の空白スペースの削除はほとんどのテキストエディタで簡単です. 開発者は、他の可視コードを含む行では特に、行の末尾に空白を入れないでください.

処理を簡略化するツールがあります.


 * nano: GNU nano 3.2;
 * Komodo Edit: メニューの「Edit > Preferences」を開きSave Optionsで「Clean trailing whitespace and EOL markers」ならびに「Only clean changed lines」を有効にする;
 * Kate: オプション「Highlight trailing spaces」を有効にすると、行末の空白スペースを表示する. 「Settings > Configure Kate > Appearance」から設定. また「Settings > Configure Kate > Open/Save」の設定で、保存時に行末の空白スペース削除を自動処理できる.
 * vim: さまざまな自動クリーンナッププラグインを備える.
 * Sublime Text: TrailingSpace処理用プラグイン (行末の空白スペースを強調表示、削除)

キーワード
キーワード (例 や ) に不要な括弧を付けない.

全般的なスタイル
MediaWikiのインデントの形式は、いわゆる字下げスタイルの1TBS あるいは OTBSと同様です. 波括弧は関数、条件文やループなどの開始と同じ行に置きます. else/elseifは前の波括弧 と同じ行に置きます.

複数行にわたる文の場合、2行目以降の行を1段深くインデントして記述します.

インデントと改行を使い、コードの論理的構造を明示します. インデントの深さを変え入れ子にした複数の波括弧あるいは同様の構造にすると、入れ子構造ごとに新しいインデントを作る場合があります.

switch文では波括弧のセット内とケースにインデントを次のように用います.

垂直方向の位置合わせ
垂直方向の配置の使用は避けます. 新しい項目を追加するたび、左カラムに適用する幅を増やす必要があり、差分表示が読み取りにくくなります.

必要に応じて、行中心で垂直位置合わせをするには、タブではなく空白スペースを使います. 例はこうなります.

これは空白スペースが半角中グロ「･」に変換され、下記の表示になります.

 $namespaceNames·=·[ → NS_MEDIA············=>·'Media', → NS_SPECIAL··········=>·'Special', → NS_MAIN·············=>·'', ]; (もしvimでアドオンtabular vim add-onを使用した場合、 :Tabularize /= と入力すると「=」符号の場所で位置合わせします. )

行の継続
1行は80桁から100桁の範囲で改行します. 特殊な例外はありますが、多数のパラメータを採用する関数は例外なく改行が必要です.

2つの行を分離する演算子は、前の行の行末に配置します.

「if」文が続くときは、オールマンのスタイル 括弧に置換して制御文と本文の区分を明示します.

制御文を区分するために必要なインデントの深さについては意見が分かれています. 本文とは異なるインデントの深さにすると、制御文の部分が本文と異なることを明示するものの、ユニバーサルな解釈ではありません.

制御文が継続して表現が長大になると、どちらの方法を使っても見た目は美しくなりません. いずれにしても最善策として、一時的な変数を使い、複数行に分割します.

波括弧で囲まない制御構造
「ブロック」は1行に記述しない. 左マージンから読者が探すはずの重要な文を、遠い位置に動かしてしまう結果になるためです. コードを短くしても簡略化したことになりません. コーディングの形式はヒトとのコミュニケーションを効率化することにあり、狭い空間にコンピュータ可読の文を押し込むことではありません.

この方法は開発者が「スマートなインデント」機能のないテキストエディタを使用している場合に特に発生しがちな、一般的な論理エラーを回避します. 1行だったブロックを後に2行に拡張した場合、このエラーが発生します.

上記に後で次の変更を加えた場合.

これにより微妙なバグが発生する可能性があります.

Emacs方式
EmacsではnXHTMLモードに代わって を使用し、 .emacsファイルにMediaWikiマイナーモードを設定できます.

上記の 関数はパスを確認し、 を呼び出したときに「mw」または「mediawiki」を含んでいるかどうか見極めると、バッファを設定してMediaWikiのソースの編集に マイナーモードを使用させます. バッファが を使用したことは、モードラインに「PHP MW」や「PHP/lw MW」のようなものが表示されると判断できます.

URL の構築
文字列の連結などの方法で手動でURLを構築しないでください. リクエストをコードが行う場合 ( 特にPOSTとバックグラウンドリクエスト) には必ず完全なURL形式を使用します.

PHPで使用できる方式は適切なまたは方式、ウィキテキストではというマジックワード、JavaScriptを使うならmw.util.getURL方式、さらに他の言語の同様の方式です. 予期せぬ短いURL構成などの問題を避けることができます.

ファイルの命名
サーバ側のコードを含むファイルには要素語の最初を大文字で書き表すアッパーキャメルケースで命名します. 拡張機能の命名規約もこの方式です. ファイル内の最も重要なクラスに基づいて命名します. ほとんどのファイルにはクラス1件のみ、もしくはベースクラスと複数のdescendantが含まれます. たとえば に含まれる クラスは1件のみです. は クラスに加えて含まれる および は両方ともそのdescendantです.

アクセスポイントのファイル
SQLなど「access point」ファイルに命名し、PHPエントリポイントの名前には や などのように小文字表記に限定しています. メンテナンスのスクリプトは一般的に小文字のキャメルケースで記述しますが、必ずしもこの限りではありません. サイト管理者が使うファイルでreadme、licensesやchangelogsなどは大文字表記です.

ファイルやディレクトリの名称に空白スペースあるいは非ASCII文字を使わないでください. 小文字表記の題名はアンダースコア (_) ではなくハイフン (-) を使うようにします.

JS、CSSとメディアの命名
JavaScript、CSSとメディアのファイル (通常はResourceLoader経由で読み込み) の命名は次の例のようにモジュールの名称と一致させます.
 * というモジュールに対応するファイル名は や がありえます.
 * というモジュールに対応するファイル名は です.

拡張機能が命名したモジュール名には のように名づける決まりで、次のような例があります.

この方法であれば、編集の利便上、単一のモジュールを細かく分割したとした後にもう一度ひとつのモジュールにまとめたとしても、ファイルを探すのが容易になります. .

説明文書
言語に特化した下位ページには、ファイル内のコードコメントの構文そのものの情報が、例えばdoxygenに対してはcomments in PHPのコメントに含まれています. 正確な構文を使用すると、http://doc.wikimedia.orgのソースコードから説明文書の生成ができます.

MediaWikiの一部の要素はコアのに説明文書があります. 例えば新しいフックを追加した場合、そのフックの名称を使ってを更新し、フックの作用とフックが用いるパラメータを記述します.

テキスト ファイル
開発者は解説文書をコードとともにGitに保管できます. この方法は拡張機能アーキテクチャやデータベース設計でコードのコミットごとに更新が必要な詳しい説明文書に適しています. Gitに説明文書を置くmediawiki.org上のページは、双方を を使ってリンクします. .

(Gitファイルからテキストをウィキに参照読み込みする可能性はT91626で追跡しています. )

多くの技術的説明ページでmediawiki.orgのページに含まれるものは、多数のリリースを重ねたMediaWikiコードの進化の記録でもあります. 変更点は個々の説明文書に記述するか、あるいは 最終版のコードベースに限定して「原本」 (master) に述べます.

テキスト ファイルの書式

 * テキストファイルがウィキ形式であれば、 拡張機能を付与します. GitHub can parse a subset of wikitext, so   files mirrored on GitHub will display some formatting (a   extension also works, but is longer). For example, the Wikibase extension's   in GitHub.
 * テキストファイルがウィキ形式であれば、 拡張機能を付与します. GitHub can parse a subset of wikitext, so   files mirrored on GitHub will display some formatting (a   extension also works, but is longer). For example, the Wikibase extension's   in GitHub.


 * Doxygen supports Markdown formatting, so you can put lightly-formatted documentation in  files. Diffusion and GitHub also support   files. Name the explanatory file for a directory or project  ; Diffusion and GitHub will display this file when you view that directory or project (e.g. RESTbase's , in  and on GitHub).
 * Doxygen supports Markdown formatting, so you can put lightly-formatted documentation in  files. Diffusion and GitHub also support   files. Name the explanatory file for a directory or project  ; Diffusion and GitHub will display this file when you view that directory or project (e.g. RESTbase's , in  and on GitHub).


 * no extension and
 * Doxygen by default parses these as C language files (!!, tracked in ). You can take advantage of this by making the file mimic a C comment, and then add doxygen directives to the file. For example, generates File backend design in doxygen, and begins with:




 * Special:Version/Credits assumes  and   (with no extension) are wikitext files.

ソースファイルのヘッダー
In order to be compliant with most licenses you should have something similar to the following (specific to GPLv2 PHP applications) at the top of every source file.

ライセンス
Licenses are generally referred to by their full name or acronym as per SPDX standard. See also Manual:$wgExtensionCredits#license.

リリースノート
You must document all significant changes (including all fixed bug reports) to the core software which might affect wiki users, server administrators, or extension authors in the  file. is in development; on every release we move the past release notes into the  file and start afresh. is generally divided into three sections:


 * Configuration changes is the place to put changes to accepted default behavior, backwards-incompatible changes, or other things which need a server administrator to look at and decide "is this change right for my wiki?". Try to include a brief explanation of how the previous functionality can be recovered if desired.
 * Bug fixes is the place to note changes which fix behavior which is accepted to be problematic or undesirable. These will often be issues reported in Phabricator, but needn't necessarily.
 * New features is, unsurprisingly, to note the addition of new functionality.

There may be additional sections for specific components (e.g. the Action API) or for miscellaneous changes that don't fall into one of the above categories.

In all cases, if your change is in response to one or more issues reported in Phabricator, include the task ID(s) at the start of the entry. Add new entries in chronological order at the end of the section.

システムメッセージ
When creating a new system message, use hyphens (-) where possible instead of CamelCase or snake_case. So for example,  is a good name, while   and   are not.

If the message is going to be used as a label which can have a colon after it, don't hardcode the colon; instead, put the colon inside the message text. Some languages (such as French which require a space before) need to handle colons in a different way, which is impossible if the colon is hardcoded. The same holds for several other types of interpunctuation.

Try to use message keys "whole" in code, rather than building them on the fly; as this makes it easier to search for them in the codebase. For instance, the following shows how a search for  will not find this use of the message key if they are not used as a whole.

If you feel that you have to build messages on the fly, put a comment with all possible whole messages nearby:

See Localisation for more conventions about creating, using, documenting and maintaining message keys.

好ましい綴り
It is just as important to have consistent spelling in the UI and codebase as it is to have consistent UI. By long standing history, 'American English' is the preferred spelling for English language messages, comments, and documentation.

メッセージキーの短縮形

 * ph
 * プレースホルダー (placeholder: 入力欄内のテキスト)


 * tip
 * ツールチップ テキスト (tooltip text)


 * tog-xx
 * 利用者の個人設定内のトグル (toggle) オプション (訳注: チェックボックス)

句点
Non-title error messages are considered as sentences and should have punctuation.

ResourceLoader
モジュール名は読みこむスクリプトのメインの定義と一致する必要があります. 例として オブジェクトを定義するモジュールの名前は"mediawiki.util"となり、 コンストラクタに対するモジュールなら"mediawiki.Title"と命名します.

コア モジュール
もしコアモジュールのその他の機能（または似ているが違う機能）が必要な場合、実際にコアモジュールを改善してください. 変更するために別の場所にあったコードをコピー&ペーストして使うことはできません.

リファクタリング
修正を加えるたびにコードのリファクタを実行：修正のだびにコードの悪化を蓄積しないでください.

ただし、リファクタリングが大量に及ぶ場合は、コミットを分割して行います. 構築ガイドArchitecture guidelines (草案) も参照してください.

HTML
MediaWiki HTTPレスポンスの出力は、2つのソースのうちの1つによって生成されます. MediaWikiのPHPコードはユーザインターフェイスの信頼できるソースであり、出力できるのは任意のHTMLです. パーサがHTMLに変換するウィキテキストでユーザが生成したものには信頼性の低いソースもあります. 「Template」名前空間には、ユーザがウィキテキストを介して作成した複雑なHTMLがしばしば見られます. パーサが生成したHTMLは、出力前にサニタイズされます.

ほとんどのデータ属性は、ユーザがウィキテキストとテンプレートで使用できるようにしてあります. しかしながら以下の制限された接頭辞は、ウィキテキストでは使用できません. この方法でクライアントJavaScriptコードから、DOM要素が信頼できるソース由来かどうか判断できます.


 * – この属性はOOUIウィジェットが生成しHTML形式で表現されます.
 * – Parsoidの内部使用限定で予約された属性です.
 * 及び – MediaWikiコア、外装 (スキン) 及び拡張機能による内部使用向けに予約済みの属性.   はParsoidでも使われます.

JavaScriptの要素を選択するとき属性のキー/値を特定すると、意図する信頼できるソース由来のDOM要素に限定して対象とするように設定できます. サンプル： 正式な差分表示のために'wikipage.diff'フックに限定して起動します.

外部リンク

 * コード スタイル ツール