mirror of
https://github.com/moodle/moodle.git
synced 2025-02-25 12:33:18 +01:00
204 lines
19 KiB
HTML
204 lines
19 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Moodle Docs: Coding Guidelines</title>
|
|
<link rel="stylesheet" href="docstyles.css" type="TEXT/CSS" />
|
|
<meta http-equiv="Content-Type" content="text/html; charset=EUC-JP" />
|
|
</head>
|
|
<body>
|
|
<h1>Moodleコーディングガイドライン</h1>
|
|
<p class="normaltext">協力的なプロジェクトを堅牢にするためには、一貫性および安定性が必要です。</p>
|
|
<p class="normaltext">このガイドラインは、Moodleコードが目指すゴールを提示するためにあります。
|
|
間違いなく、いくつかの古いコードは少数の場所で目標基準に達していませんが、最終的に修正します。
|
|
すべての新しいコードは、これらの基準を可能な限り確実に順守してください。</p>
|
|
<h2>一般ルール</h2>
|
|
<ol class="normaltext">
|
|
<li class="spaced">すべてのコードファイルは、.php拡張子を使用してください。</li>
|
|
<li class="spaced">すべてのテンプレートファイルは、.html拡張子を使用してください。</li>
|
|
<li class="spaced">すべてのテキストファイルは、Unixスタイルのテキストフォーマットを使用してください。 ( ほとんどのテキストエディタには、このオプションがあります。 )</li>
|
|
<li class="spaced">すべてのphpタグは、<font color="#339900"><?php ?></font> のように「フルタグ」を使用してください ... <font color="#339900"><? ?></font> のように「ショートタグ」ではなく。</li>
|
|
<li class="spaced">すべての著作権情報は保持してください。必要であれば、あなた独自の情報を追加することができます。</li>
|
|
<li class="spaced">各ファイルでは、config.phpをインクルードしてください。</li>
|
|
<li class="spaced">各ファイルでは、require_login() および isadmin()、isteacher()、iscreator() または isstudent() を使用してユーザが正しく認証されているか確認してください。</li>
|
|
<li class="spaced">データベースへのアクセスは、可能な場合は常に関数 lib/datalib.php を使用してください - この関数により幅広いデータベースの互換性を実現します。この関数を使用することにより、ほとんどのことが実現できることに気付くでしょう。SQLコードを書く必要がある場合、次のことを確認してください: クロスプラットフォームであること、あなたのコードが特定の関数 ( 通常、lib.phpファイル ) に限定されていること、明確に注釈がなされていること。</li>
|
|
<li class="spaced">$CFG、$SESSION、$THEME および $USER のような標準的なもの以外、グローバル変数を作成または使用しないでください。</li>
|
|
<li class="spaced">すべての変数は使用する前に初期化するか、少なくとも isset() または empty() を使用して存在チェックを行ってください。</li>
|
|
<li class="spaced">すべてのストリングは翻訳できるようにしてください - 「lang/en」内のファイルに新しい簡潔な英語の小文字でテキストを作成して、あなたのコードから get_string() または print_string() を使用して取り出してください。</li>
|
|
<li class="spaced">すべてのヘルプファイルは翻訳できるようにしてください - 「en/help」ディレクトリ内に新しいテキストを作成して、helpbutton() でコールしてください。
|
|
<p>ヘルプファイルを更新したい場合は: </p>
|
|
<ul>
|
|
<li>小規模の変更の場合、古い翻訳ファイルはまだ意味をなすため、変更することが可能ですが、translation@moodle.org にご連絡ください。</li>
|
|
<li>大規模の変更の場合、翻訳者が新しいバージョンのファイルだと簡単に分かるように、インクリメントした番号を付加した新しいファイル ( 例 filename2.html ) を追加してください。当然、新しいコードおよびヘルプインデックスファイルは、最新バージョンをポイントするように修正する必要もあります。</li>
|
|
</ul>
|
|
|
|
</li>
|
|
<li class="spaced">ブラウザから ( GET または POST 経由で ) 入ってくるデータは、( PHPの設定に関わらず ) 安全にデータベースにインサートできるよう、自動的に magic_quotes が適用されます。他のすべての生データ ( ファイルまたはデータベース ) は、データベースにインサートする前に <font color="#339900">addslashes()</font> でエスケープしてください。</li>
|
|
<li class="spaced">重要: Moodle内のすべてのテキスト、特にユーザによって入力されるものは format_text() 関数を使用してプリントしてください。これによりテキストは、正確にフィルタおよびクリーニングされます。</li>
|
|
</ol>
|
|
<p> </p>
|
|
<h2>コーディングスタイル</h2>
|
|
<p class="normaltext">他のスタイルを使用してきた場合、あなたのスタイルを変更することは少々面倒なことであると私は理解しています。しかし、後で人々が雑多なスタイルが使用されたMoodleコードの意味を理解する面倒さと、この面倒さのバランスを取る必要があります。人々が使用するスタイルには、明らかに良い部分もありますが、現在のスタイルは<strong>このスタイル</strong>ですので、どうか従ってください。</p>
|
|
<ol class="normaltext">
|
|
<li class="spaced"><strong>インデント</strong> は連続した4つのスペースにしてください。タブは使用しないでください。</li>
|
|
<li class="spaced"><strong>変数名</strong> は常に読みやすく、意味のある英語小文字にしてください。本当に1語以上の単語が必要な場合、単語を連結して可能な限り短くしてください。配列オブジェクト名には、複数形を使用してください。
|
|
<p class="examplecode"><font color="#006600">良い: $quiz<br />
|
|
良い: $errorstring<br />
|
|
良い: $assignments (for an array of objects)<br />
|
|
良い: $i (but only in little loops)<br />
|
|
<br />
|
|
悪い: $Quiz <br />
|
|
悪い: $aReallyLongVariableNameWithoutAGoodReason<br />
|
|
悪い: $error_string</font></p>
|
|
</li>
|
|
<li class="spaced"><strong>定数</strong> は常に大文字を使用して、常にモジュール名で始めてください。単語はアンダースコア ( _ ) で別けてください。
|
|
<p class="examplecode"><font color="#006600">define("FORUM_MODE_FLATOLDEST",
|
|
1);</font></p>
|
|
</li>
|
|
<li class="spaced"><strong>関数名</strong> は単純な英語の小文字の単語を使用して、モジュール間のコンフリクトを避けるため、モジュール名で始めてください。
|
|
単語はアンダースコア ( _ ) で別けてください。可能でしたら、パラメータは常に適切なデフォルト値を持つようにしてください。
|
|
関数名および続く ( 大括弧 ) の間にはスペースを入れないことに注意してください。
|
|
<br />
|
|
<p class="examplecode"> <font color="#007700">function </font><font color="#0000BB">forum_set_display_mode</font><font color="#007700">(</font><font color="#0000BB">$mode</font><font color="#007700">=</font><font color="#0000BB">0</font><font color="#007700">)
|
|
{<br />
|
|
global </font><font color="#0000BB">$USER</font><font color="#007700">,
|
|
</font><font color="#0000BB">$CFG</font><font color="#007700">;<br />
|
|
<br />
|
|
if (</font><font color="#0000BB">$mode</font><font color="#007700">)
|
|
{<br />
|
|
</font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode
|
|
</font><font color="#007700">= </font><font color="#0000BB">$mode</font><font color="#007700">;<br />
|
|
} else if (empty(</font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode</font><font color="#007700">))
|
|
{<br />
|
|
</font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode
|
|
</font><font color="#007700">= </font><font color="#0000BB">$CFG</font><font color="#007700">-></font><font color="#0000BB">forum_displaymode</font><font color="#007700">;<br />
|
|
}<br />
|
|
}</font></p>
|
|
</li>
|
|
<li class="spaced"><strong>ブロック</strong> は ( 1行のみでも ) 常に丸括弧で囲んでください。Moodleは、このようなスタイルを使用します。
|
|
<p class="examplecode"> <font color="#006600">if (</font><font color="#0000CC">$quiz</font><font color="#006600">-></font><font color="#0000CC">attempts</font><font color="#006600">)
|
|
{<br />
|
|
if (</font><font color="#0000CC">$numattempts </font><font color="#006600">>
|
|
</font><font color="#0000CC">$quiz</font><font color="#006600">-></font><font color="#0000CC">attempts</font><font color="#006600">)
|
|
{<br />
|
|
</font><font color="#0000CC">error</font><font color="#006600">(</font><font color="#0000BB">$strtoomanyattempts</font><font color="#006600">,
|
|
</font><font color="#CC0000">"view.php?id=$cm</font><font color="#006600">-></font><font color="#CC0000">id"</font><font color="#006600">);<br />
|
|
}<br />
|
|
}</font></p>
|
|
</li>
|
|
<li class="spaced"><strong>文字列</strong> は処理速度を増すため、可能であればシングル・クオテーションで定義してください。<br />
|
|
<p class="examplecode"> <font color="#006600">$var = 'some text without any
|
|
variables';<br />
|
|
$var = "with special characters like a new line \n";<br />
|
|
$var = 'a very, very long string with a '.$single.' variable in it';<br />
|
|
$var = "some $text with $many variables $within it"; </font></p>
|
|
</li>
|
|
|
|
<li class="spaced"><strong>コメント</strong> は可能な限り実用的に追加し、コードの流れ、関数および変数の目的を説明してください。
|
|
<ul>
|
|
<li>すべての関数 ( およびクラス ) は、評判の良い <a target="_blank" href="http://www.phpdoc.org/">phpDocフォーマット</a> を使用してください。
|
|
phpDocにより、コードドキュメンテーションを自動的に生成することができます。</li>
|
|
<li>インラインコメントは、 // スタイルを使用し、コードおよび行が並ぶよう、きちんとレイアウトしてください。</li>
|
|
</ul>
|
|
|
|
<p class="examplecode"><font color="#FF8000">
|
|
/**<br />
|
|
* The description should be first, with asterisks laid out exactly<br />
|
|
* like this example. If you want to refer to a another function,<br />
|
|
* do it like this: {@link clean_param()}. Then, add descriptions <br />
|
|
* for each parameter as follows.<br />
|
|
*<br />
|
|
* @param int $postid The PHP type is followed by the variable name<br />
|
|
* @param array $scale The PHP type is followed by the variable name<br />
|
|
* @param array $ratings The PHP type is followed by the variable name<br />
|
|
* @return mixed<br />
|
|
*/</font><br />
|
|
<font color="#006600">function </font><font color="#0000BB">forum_get_ratings_mean</font><font color="#007700">(</font><font color="#0000BB">$postid</font><font color="#007700">,
|
|
</font><font color="#0000BB">$scale</font><font color="#007700">, </font><font color="#0000BB">$ratings</font><font color="#007700">=</font><font color="#0000BB">NULL</font><font color="#007700">)
|
|
{<br /></font>
|
|
<font color="#007700">if (!</font><font color="#0000BB">$ratings</font><font color="#007700">)
|
|
{<br />
|
|
</font><font color="#0000BB">$ratings
|
|
</font><font color="#007700">= array(); </font><font color="#FF8000">//
|
|
Initialize the empty array</font><font color="#007700"><br />
|
|
if (</font><font color="#0000BB">$rates
|
|
</font><font color="#007700">= </font><font color="#0000BB">get_records</font><font color="#007700">(</font><font color="#DD0000">"forum_ratings"</font><font color="#007700">,
|
|
</font><font color="#DD0000">"post"</font><font color="#007700">, </font><font color="#0000BB">$postid</font><font color="#007700">))
|
|
{<br />
|
|
</font><font color="#FF8000">//
|
|
Process each rating in turn</font><font color="#007700"><br />
|
|
foreach
|
|
(</font><font color="#0000BB">$rates </font><font color="#007700">as </font><font color="#0000BB">$rate</font><font color="#007700">)
|
|
{</font> <br />
|
|
....etc </p>
|
|
</li>
|
|
|
|
<li class="spaced"><strong>スペース</strong> は自由に使用してください - 明快さを得るために、物事を少し広げることを恐れないでください。一般的に、
|
|
大括弧と標準的な命令文の間には1つのスペースを入れますが、大括弧と変数および関数の間にはスペースを入れません。
|
|
<br />
|
|
<p class="examplecode"> <font color="#007700">foreach (</font><font color="#0000BB">$objects
|
|
</font><font color="#007700">as </font><font color="#0000BB">$key </font><font color="#007700">=></font><font color="#0000BB">
|
|
$thing</font><font color="#007700">)</font><font color="#006600"> {<br />
|
|
</font><font color="#007700"> </font><font color="#0000BB">process($thing);</font><font color="#006600">
|
|
<br />
|
|
} <br />
|
|
<br />
|
|
</font><font color="#007700">if (</font><font color="#0000BB">$x </font><font color="#007700">==
|
|
</font><font color="#0000BB">$y</font><font color="#007700">)</font><font color="#006600">
|
|
{<br />
|
|
</font><font color="#007700"> </font><font color="#0000BB">$a
|
|
</font><font color="#007700">= </font><font color="#0000BB">$b</font><font color="#007700">;</font><font color="#006600"><br />
|
|
} else if (</font><font color="#0000BB">$x </font><font color="#007700">==
|
|
</font><font color="#0000BB">$z</font><font color="#006600">) {<br />
|
|
</font><font color="#007700"> </font><font color="#0000BB">$a
|
|
</font><font color="#007700">= </font><font color="#0000BB">$c</font><font color="#007700">;</font><font color="#006600"><br />
|
|
} else {<br />
|
|
</font><font color="#007700"> </font><font color="#0000BB">$a
|
|
</font><font color="#007700">= </font><font color="#0000BB">$d</font><font color="#007700">;</font><font color="#006600"><br />
|
|
} </font></p>
|
|
</li>
|
|
</ol>
|
|
<p> </p>
|
|
<h2>データベース構造</h2>
|
|
<ol class="normaltext">
|
|
<li class="spaced">すべてのテーブルは、プライマリインデックスとして auto-incrementing <strong>id</strong> フィールド ( INT10 ) を持つ必要があります。</li>
|
|
<li class="spaced">各モジュールのインスタンスを含むメインテーブルは、モジュールと同じ名称を持ち ( 例 <strong>widget</strong> )、次の最小限のフィールドを含む必要があります:
|
|
<ul>
|
|
<li><strong>id</strong> - 上記で説明</li>
|
|
<li><strong>course</strong> - 各インスタンスが属するコースID</li>
|
|
<li><strong>name</strong> - 各モジュールのインスタンスのフルネーム</li>
|
|
</ul>
|
|
</li>
|
|
<li class="spaced">モジュールと関連する他のテーブルで「things」に関する情報を含むものは <strong>widget_things</strong> という名称を付けてください ( 複数形に注意してください )。</li>
|
|
<li class="spaced">カラムの名称は、変数名と同じルールに従って簡単かつ短くつけてください。</li>
|
|
<li class="spaced">可能であれば、他のテーブルのidフィールドへの参照を含むカラム ( 例 <strong>widget</strong> ) は、<strong>widgetid</strong>と呼ばれるべきです。( この仕様は、やや新しいもので、他のいくつかの古いテーブルには適用されていないことに注意してください。)</li>
|
|
<li class="spaced">論理値 ( Boolean ) フィールドは、必要に応じて後で値を拡張できるよう、0または1を含む整数フィールド ( 例 INT4 ) を使用してください。</li>
|
|
<li class="spaced">ほとんどのフィールドは、PHP <strong>time</strong>() 関数から現在のタイムスタンプで更新される <strong>timemodified</strong> フィールド ( INT10 ) を持つ必要があります。</li>
|
|
</ol>
|
|
<p> </p>
|
|
<h2>セキュリティ問題 ( およびフォームおよびURLデータの取り扱い )</h2>
|
|
<ol class="normaltext">
|
|
<li class="spaced">「register_globals」を信頼しないでください。<strong>すべての</strong>変数は、<strong>すべての</strong>コードファイルで適切に初期化してください。変数がどこから来たか明らかでなければなりません。</li>
|
|
<li class="spaced">空でもすべての配列およびオブジェクトを初期化してください。<code>$a = array()</code> または <code>$obj = new stdClass();</code>。</li>
|
|
<li class="spaced"><code>optional_variable()</code> 関数は使用しないでください。代わりに <code>optional_param()</code> 関数を使用してください。あなたが必要なデータタイプのために正しい PARAM_XXXX 値を選択してください。変数の任意の値をチェックおよびセットする場合、<code>set_default()</code> 関数を使用してください。</li>
|
|
<li class="spaced"><code>require_variable()</code> 関数を使用しないでください。代わりに <code>required_param()</code> 関数を使用してください。あなたが必要なデータタイプのために正しい PARAM_XXXX 値を選択してください。</li>
|
|
<li class="spaced">気をつけて <code>data_submitted()</code> を使用してください。データは使用される前に、さらにきれいにする必要があります。</li>
|
|
<li class="spaced"><code>$_GET</code>、<code>$_POST</code> または <code>$_REQUEST</code> を使用しないでください。必要に応じて、適切な <code>required_param()</code> または <code>optional_param()</code> を使用してください。</li>
|
|
<li class="spaced"><code>if (isset($_GET['something']))</code> のようなものを使用して動作をチェックしないでください。例えば <code>$something = optional_param( 'something',-1,PARAM_INT )</code> を使用して、適切な値の幅に入っているかテストしてください。例 <code>if ($something>=0) {...</code></li>
|
|
<li class="spaced">簡単に探すことができるよう、可能な限りすべての <code>required_param()</code>、<code>optional_param()</code> および他の変数を各ファイルの最初で初期化してください。</li>
|
|
<li class="spaced">フォーム処理ルーチンをアタックから保護するために「sesskey」メカニズムを使用してください。基本的な使用例: フォームが生成される時に、
|
|
include <code><input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" /></code> と使用します。フォームの処理を行う時は、 <code>if (!confirm_sesskey()) {error('Bad Session Key');}</code> でチェックしてください。</li>
|
|
<li class="spaced"><code>required_param()</code> または <code>optional_param()</code> の適切な使用で「きれいにされていない」場合、すべてのファイルは <code>clean_filename()</code> 関数を使用して「きれいにする」必要があります。</li>
|
|
<li class="spaced">データベースから読み込んだデータは、更新する前に <code>addslashes()</code> を適用してください。データオブジェクト全体は、<code>addslashes_object()</code> で一度に処理することができます。</li>
|
|
<li class="spaced">可能な限り、データベースに保存するデータは、<code>GET</code>データ ( 例 URLラインからのデータ ) とは対照的な <code>POST</code>データ ( <code>method="POST"</code> によるフォームデータ ) を使用してください。</li>
|
|
<li class="spaced">避けることができるなら <code>$_SERVER</code> からのデータを使用しないでください。これは移植性に問題があります。</li>
|
|
<li class="spaced">他で行っていない場合、データベースに書き込むすべてのデータを適切なデータタイプのPARAM_XXXXを使用して <code>clean_param()</code> 関数に通してください。</li>
|
|
<li class="spaced">あなたがカスタムSQLコードを記述する場合、間違いなく正しいことを確認してください。特に値の周囲のクォート漏れに気をつけてください。SQLインジェクションの脆弱性 ( exploit ) となる可能性があります。</li>
|
|
<li class="spaced"><strong>すべての</strong>ファイルで使用されるすべてのデータ ( 特にデータベースに書き込む部分) をチェックしてください。他でチェックされることを期待したり、信頼しないでください。</li>
|
|
<li class="spaced">インクルードされるコードのブロックは、明確なPHP構造を含むべきです ( 例 クラス宣言、関数定義等 ) - 連続したコードのブロックは、初期化無しの変数使用を奨励してしまいます。</li>
|
|
</ol>
|
|
<hr />
|
|
<p align="center"><font size="1"><a href="." target="_top">Moodleドキュメンテーション</a></font></p>
|
|
<p align="center"><font size="1">Version: $Id$</font></p>
|
|
</body>
|
|
</html> |