開発:コーディング

印刷用ページはサポート対象外です。表示エラーが発生する可能性があります。ブラウザーのブックマークを更新し、印刷にはブラウザーの印刷機能を使用してください。

再作成中です - Mitsuhiro Yoshida 2010年1月9日 (土) 15:47 (UTC)

このページは、Moodleのコーディングガイドラインに関して記述する、トップレベルのページです。あなたがMoodleコードの書き方を知りたい場合、最初に読むべきスタートページでもあります。

警告: このページは、現在作成中です!

Moodleアーキテクチャ

Moodle tries to run on the widest possible range of platforms, for the widest possible number of people, while remaining easy to install, use, upgrade and integrate with other systems.

For more about this, see: Moodle architecture.

プラグイン

Moodle has a general philosophy of modularity. There are over 25 different types of plugins, however many of these plugin types work the same way.

For more about the structure of plugins, see Moodle plugins.

コーディングスタイル

Consistent coding style is important in any development project, and particularly so when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Writing your code in this way is an important step to having your code accepted by the Moodle community.

Our Moodle coding style document explains this standard.

セキュリティ

Security is about protecting the interests and data of all our users. Moodle may not be banking software, but it is still protecting a lot of sensitive and important data such as private discussions and grades from outside eyes (or student hackers!) as well as protecting our users from spammers and other internet predators.

It's also a script running on people's servers, so Moodle needs to be a responsible Internet citizen and not introduce vulnerabilities that could allow crackers to gain unlawful access to the server it runs on.

Any single script (in Moodle core or a third party module) can introduce a vulnerability to thousands of sites, so it's important that all developers strictly follow our Moodleセキュリティガイドライン.

XHTMLおよびCSS

It's important that Moodle produces strict, well-formed XHTML code, compliant with all common accessibility guidelines (such as W3C WAG).

CSS should be used for layout. Moodle comes with several themes installed. The 'standard' theme, which should be a plain theme suitable to act as a building block for other themes. That should contain the minimal styling to make Moodle look OK and be function. Then Moodle comes with several other default themes that look good and demonstrate various techniques for building themes.

This helps consistency across browsers in a nicely-degrading way (especially those using non-visual or mobile browsers), as well as improving life for theme designers.

Full information is here: Moodle XHTML

Javaスクリプト

In general, everything in Moodle should work with JavaScript turned off in your browser. If you do have JavaScript enabled it should only improve usability (not add features).

This is important for accessibility, and in line with the principles of unobtrusive JavaScript and progressive enhancement.

See the Moodle JavaScript guidelines for more information.

国際化

Moodle works in over 81 languages because we pay great attention to keeping the language strings and locale information separate from the code, in language packs.

The default language for all code and documentation, however, is English (AU).

Full details: Moodle Internationalisation

アクセシビリティ

Moodle should work well for the widest possible range of people.

See: Moodle Accessibility

ユーザビリティ

See: Moodle User Interface Guidelines (being produced summer 2009)

Implementing user interfaces: Interface Guidelines

パフォーマンス

The load any Moodle site can cope with will, of course, depend on the server and network hardware that it is running on.

The most important property is scalability, so a small increase in the number of users, courses, activities in a course, and so on, only causes a correspondingly small increase in server load.

For more information and advice, see Performance and scalability.

データベース

Moodle has a powerful database abstraction layer that we wrote ourselves, called XMLDB. This lets the same Moodle code work on MySQL, PostgreSQL, Oracle and MSSQL.

We have tools and API for defining and modifying tables as well as methods for getting data in and out of the database.

Overview: Moodle Database guidelines

イベント

Moodle allows inter-module communication via events. Modules can trigger specific events and other modules can choose to handle those events.

Full information: Moodle Events API

単体テスト

Unit testing is not simply a technique but a philosophy of software development.

The idea is to create automatable tests for each bit of functionality that you are developing (at the same time you are developing it). This not only helps everyone later test that the software works, but helps the development itself, because it forces you to work in a modular way with very clearly defined structures and goals.

Moodle uses a library called simpletest (not very extensively yet though!) that makes writing unit tests fairly simple. Our unit testing is currently not deep but we want to improve this.

Full information here: Moodle Unit Tests

一般ルール

すべてのコードファイルは、.php拡張子を使用してください。
すべてのテンプレートファイルは、.html拡張子を使用してください。
すべてのテキストファイルは、Unixスタイルのテキストフォーマットを使用してください。 ( ほとんどのテキストエディタには、このオプションがあります。 )
すべてのphpタグは、<?php ?> のように「フルタグ」を使用してください ... <? ?> のように「ショートタグ」ではなく。
すべての著作権情報は保持してください。必要であれば、あなた独自の情報を追加することができます。
各ファイルでは、config.phpをインクルードしてください。
各ファイルでは、require_login() および isadmin()、isteacher()、iscreator() または isstudent() を使用してユーザが正しく認証されているか確認してください。
データベースへのアクセスは、可能な場合は常に関数 lib/datalib.php を使用してください - この関数により幅広いデータベースの互換性を実現します。この関数を使用することにより、ほとんどのことが実現できることに気づくでしょう。SQLコードを書く必要がある場合、次のことを確認してください: クロスプラットフォームであること、あなたのコードが特定の関数 ( 通常、lib.phpファイル ) に限定されていること、明確に注釈がなされていること。
$CFG、$SESSION、$THEME および $USER のような標準的なもの以外、グローバル変数を作成または使用しないでください。
すべての変数は使用する前に初期化するか、少なくとも isset() または empty() を使用して存在チェックを行ってください。
すべてのストリングは翻訳できるようにしてください - 「lang/en」内のファイルに新しい簡潔な英語の小文字でテキストを作成して、あなたのコードから get_string() または print_string() を使用して取り出してください。
すべてのヘルプファイルは翻訳できるようにしてください - 「en/help」ディレクトリ内に新しいテキストを作成して、helpbutton() でコールしてください。ヘルプファイルを更新したい場合は:
- 小規模の変更の場合、古い翻訳ファイルはまだ意味をなすため、変更することが可能ですが、translation@moodle.org にご連絡ください。
- 大規模の変更の場合、翻訳者が新しいバージョンのファイルだと簡単に分かるように、インクリメントした番号を付加した新しいファイル ( 例 filename2.html ) を追加してください。当然、新しいコードおよびヘルプインデックスファイルは、最新バージョンをポイントするように修正する必要もあります。
ブラウザから ( GET または POST 経由で ) 入ってくるデータは、( PHPの設定に関わらず ) 安全にデータベースにインサートできるよう、自動的に magic_quotes が適用されます。他のすべての生データ ( ファイルまたはデータベース ) は、データベースにインサートする前に addslashes() でエスケープしてください。
重要: Moodle内のすべてのテキスト、特にユーザによって入力されるものは format_text() 関数を使用してプリントしてください。これによりテキストは、正確にフィルタおよびクリーニングされます。
ユーザログは、add_to_log()関数を使用して記録してください。これらのログは、活動レポートおよびログで使用されます。

コーディングスタイル

他のスタイルを使用してきた場合、あなたのスタイルを変更することは少々面倒なことであると私は理解しています。しかし、後で人々が雑多なスタイルが使用されたMoodleコードの意味を理解する面倒さと、この面倒さのバランスを取る必要があります。人々が使用するスタイルには、明らかに良い部分もありますが、現在のスタイルはこのスタイルですので、どうか従ってください。

1. インデントは連続した4つのスペースにしてください。タブは使用しないでください。

2. 変数名は常に読みやすく、意味のある英語小文字にしてください。本当に1語以上の単語が必要な場合、単語を連結して可能な限り短くしてください。配列オブジェクト名には、複数形を使用してください。

     良い: $quiz
     良い: $errorstring
     良い: $assignments (for an array of objects)
     良い: $i (but only in little loops)

     悪い: $Quiz
     悪い: $aReallyLongVariableNameWithoutAGoodReason
     悪い: $error_string

3. 定数は常に大文字を使用して、常にモジュール名で始めてください。単語はアンダースコア ( _ ) で別けてください。

     define("FORUM_MODE_FLATOLDEST", 1);

4. 関数名は単純な英語の小文字の単語を使用して、モジュール間のコンフリクトを避けるため、モジュール名で始めてください。単語はアンダースコア ( _ ) で別けてください。可能でしたら、パラメータは常に適切なデフォルト値を持つようにしてください。関数名および続く ( 大括弧 ) の間にはスペースを入れないことに注意してください。

     function forum_set_display_mode($mode=0) {
         global $USER, $CFG;
         
         if ($mode) {
             $USER->mode = $mode;
         } else if (empty($USER->mode)) {
             $USER->mode = $CFG->forum_displaymode;
         }
     }

5. ブロックは ( 1行のみでも ) 常に丸括弧で囲んでください。Moodleは、このようなスタイルを使用します。

     if ($quiz->attempts) {
         if ($numattempts > $quiz->attempts) {
             error($strtoomanyattempts, "view.php?id=$cm->id");
         }
     }

6. 文字列は処理速度を増すため、可能であればシングル・クオテーションで定義してください。

     $var = 'some text without any variables';
     $var = "with special characters like a new line \n";
     $var = 'a very, very long string with a '.$single.' variable in it';
     $var = "some $text with $many variables $within it";

7. コメントは可能な限り実用的に追加し、コードの流れ、関数および変数の目的を説明してください。

すべての関数 ( およびクラス ) は、評判の良い phpDocフォーマットを使用してください。 phpDocにより、コードドキュメンテーションを自動的に生成することができます。
インラインコメントは、 // スタイルを使用し、コードおよび行が並ぶよう、きちんとレイアウトしてください。

     /**
     * The description should be first, with asterisks laid out exactly
     * like this example. If you want to refer to a another function,
     * do it like this: {@link clean_param()}. Then, add descriptions
     * for each parameter as follows.
     *
     * @param int $postid The PHP type is followed by the variable name
     * @param array $scale The PHP type is followed by the variable name
     * @param array $ratings The PHP type is followed by the variable name
     * @return mixed
     */
     function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
         if (!$ratings) {
             $ratings = array();     // Initialize the empty array
             if ($rates = get_records("forum_ratings", "post", $postid)) {
                 // Process each rating in turn
                 foreach ($rates as $rate) {
     ....etc

8. スペースは自由に使用してください - 明快さを得るために、物事を少し広げることを恐れないでください。一般的に、大括弧と標準的な命令文の間には1つのスペースを入れますが、大括弧と変数および関数の間にはスペースを入れません。

     foreach ($objects as $key => $thing) {
         process($thing);
     }
     
     if ($x == $y) {
         $a = $b;
     } else if ($x == $z) {
         $a = $c;
     } else {
         $a = $d;
     }

9. オブジェクトのコピーを作成する場合、常にphp5 clone() 関数 ( そうでなければ最初のオブジェクトの参照で終わります ) を使用してください。Moodleは、これがphp4でも間違いなく動作するようにします。

     悪い:   $b = $a;
     良い:  $b = clone($a);

あなたがコピーしたいものがオブジェクトではない ( 例オブジェクトの配列 ) 場合、代わりにfullclone() 関数を使用してください。

データベース構造

すべてのテーブルは、プライマリインデックスとして auto-incrementing id フィールド ( INT10 ) を持つ必要があります。
各モジュールのインスタンスを含むメインテーブルは、モジュールと同じ名称を持ち ( 例 widget )、次の最小限のフィールドを含む必要があります:
- id - 上記で説明
- course - 各インスタンスが属するコースID
- name - 各モジュールのインスタンスのフルネーム
モジュールと関連する他のテーブルで「things」に関する情報を含むものは widget_things という名称を付けてください ( 複数形に注意してください )。
カラムの名称は、変数名と同じルールに従って簡単かつ短くつけてください。
可能であれば、他のテーブルのidフィールドへの参照を含むカラム ( 例 widget ) は、widgetidと呼ばれるべきです。( この仕様は、やや新しいもので、他のいくつかの古いテーブルには適用されていないことに注意してください。)
論理値 ( Boolean ) フィールドは、必要に応じて後で値を拡張できるよう、0または1を含む整数フィールド ( 例 INT4 ) を使用してください。
ほとんどのフィールドは、PHP time() 関数から現在のタイムスタンプで更新される timemodified フィールド ( INT10 ) を持つ必要があります。

セキュリティ関連 ( およびフォームおよびURLデータの取り扱い )

「register_globals」を信頼しないでください。すべての変数は、すべてのコードファイルで適切に初期化してください。変数がどこから来たか明らかでなければなりません。
空でもすべての配列およびオブジェクトを初期化してください。$a = array() または $obj = new stdClass();。
optional_variable() 関数は使用しないでください。代わりに optional_param() 関数を使用してください。あなたが必要なデータタイプのために正しい PARAM_XXXX 値を選択してください。変数の任意の値をチェックおよびセットする場合、set_default() 関数を使用してください。
require_variable() 関数を使用しないでください。代わりに required_param() 関数を使用してください。あなたが必要なデータタイプのために正しい PARAM_XXXX 値を選択してください。
気をつけて data_submitted() を使用してください。データは使用される前に、さらにきれいにする必要があります。
$_GET、$_POST または $_REQUEST を使用しないでください。必要に応じて、適切な required_param() または optional_param() を使用してください。
if (isset($_GET['something'])) のようなものを使用して動作をチェックしないでください。例えば $something = optional_param( 'something',-1,PARAM_INT ) を使用して、適切な値の幅に入っているかテストしてください。例 if ($something>=0) {...
簡単に探すことができるよう、可能な限りすべての required_param()、optional_param() および他の変数を各ファイルの最初で初期化してください。
フォーム処理ルーチンをアタックから保護するために「sesskey」メカニズムを使用してください。基本的な使用例: フォームが生成されるときに、 include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" /> と使用します。フォームの処理を行うときは、 if (!confirm_sesskey()) {error('Bad Session Key');} でチェックしてください。
required_param() または optional_param() の適切な使用で「きれいにされていない」場合、すべてのファイルは clean_filename() 関数を使用して「きれいにする」必要があります。
データベースから読み込んだデータは、更新する前に addslashes() を適用してください。データオブジェクト全体は、addslashes_object() で一度に処理することができます。
可能な限り、データベースに保存するデータは、GETデータ ( 例 URLラインからのデータ ) とは対照的な POSTデータ ( method="POST" によるフォームデータ ) を使用してください。
避けることができるなら $_SERVER からのデータを使用しないでください。これは移植性に問題があります。
他で行っていない場合、データベースに書き込むすべてのデータを適切なデータタイプのPARAM_XXXXを使用して clean_param() 関数に通してください。
あなたがカスタムSQLコードを記述する場合、間違いなく正しいことを確認してください。特に値の周囲のクォート漏れに気をつけてください。SQLインジェクションの脆弱性 ( exploit ) となる可能性があります。
すべてのファイルで使用されるすべてのデータ ( 特にデータベースに書き込む部分) をチェックしてください。他でチェックされることを期待したり、信頼しないでください。
インクルードされるコードのブロックは、明確なPHP構造を含むべきです ( 例クラス宣言、関数定義等 ) - 連続したコードのブロックは、初期化なしの変数使用を奨励してしまいます。

Documentation

開発:コーディング

目次

Moodleアーキテクチャ

プラグイン

コーディングスタイル

セキュリティ

XHTMLおよびCSS

Javaスクリプト

国際化

アクセシビリティ

ユーザビリティ

パフォーマンス

データベース

イベント

単体テスト

関連情報

一般ルール

コーディングスタイル

データベース構造

セキュリティ関連 ( およびフォームおよびURLデータの取り扱い )