mirror of
https://github.com/moodle/moodle.git
synced 2025-02-24 12:03:12 +01:00
314 lines
19 KiB
HTML
314 lines
19 KiB
HTML
<html>
|
|
<head>
|
|
<title>Tài liệu Moodle: Các hướng dẫn Code</title>
|
|
<link rel="stylesheet" href="docstyles.css" type="TEXT/CSS">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
</head>
|
|
<body bgcolor="#ffffff">
|
|
<h1>Các hướng dẫn về coding trong Moodle</h1>
|
|
<p class="normaltext">Bất kỳ một dự án nào cũng
|
|
cần tính nhất quán và ổn định để có
|
|
thể tồn tại lâu dài.</p>
|
|
<p class="normaltext">Các hướng dẫn sau cung cấp một
|
|
mục tiêu chung để tất cả các mã Moodle có
|
|
thể phát triển tốt. Sự thật là một vài các
|
|
đoạn mã tồn tại trước đó chưa
|
|
đáp ứng được một vài yêu cầu, tuy nhiên
|
|
nó sẽ được sửa sau này. Tất cả các mã
|
|
mới phải tuân theo một cách hoàn toàn các chuẩn
|
|
dưới đây càng chính xác càng tốt.</p>
|
|
<h2>General Rules</h2>
|
|
<ol class="normaltext">
|
|
<li class="spaced">
|
|
Tất cả các file mã phải sử dụng phần
|
|
mở rộng .php.
|
|
<li class="spaced">
|
|
Tất cả các file mẫu phải sử dụng phần
|
|
mở rộng .html.
|
|
<li class="spaced">
|
|
Tẩt các file text nên sử dụng định dạng
|
|
kiểu Unix (đa số các bộ soạn thảo text có
|
|
lựa chọn này).
|
|
<li class="spaced">
|
|
Tất cả các thẻ PHP phải là các thẻ
|
|
'đầy đủ' giống như <font color="#339900"><?php
|
|
?></font> ... không phải là các thẻ 'ngắn' giống
|
|
như <font color="#339900"><? ?></font>.
|
|
<li class="spaced">
|
|
Tất cả các chú thích về bản quyền phải
|
|
được giữ nguyên. Bạn có thể đưa
|
|
thêm của bạn vào nếu cần thiết.
|
|
<li class="spaced">
|
|
Mỗi file nên gồm file chính config.php.
|
|
<li class="spaced">
|
|
Mỗi file nên kiểm tra rằng người dùng
|
|
được chứng thực đúng đắn, sử
|
|
dụng require_login() và isadmin(), isteacher(), iscreator() hoặc
|
|
isstudent().
|
|
<li class="spaced">
|
|
Tất cả các truy cập tới các cơ sở dữ
|
|
liệu phải sử dụng các hàm trong lib/datalib.php
|
|
bất cứ khi nào có thể - nó đảm bảo tính
|
|
khả chuyển giữa nhiều cơ sở dữ
|
|
liệu khác nhau. Bạn có thể tìm thấy đa số
|
|
mọi thứ là có thể bằng cách sử dụng các hàm
|
|
này. Nếu bạn phải viết mã SQL hãy đảm
|
|
bảo rằng: không phụ thuộc nền; hạn
|
|
chế các hàm cụ thể ngay trong file của bạn
|
|
(thương là trong lib.php ); và được đánh
|
|
dấu, chú thích cẩn thận, rõ ràng.
|
|
<li class="spaced">
|
|
Đừng tạo hoặc sử dụng các biến toàn
|
|
cục trừ các biến chuẩn $CFG, $SESSION, $THEME và $USER.
|
|
<li class="spaced">
|
|
Tất cả các biến nên được khởi tạo
|
|
hoặc ít nhất được thử tính tồn
|
|
tại thông qua sử dụng isset() hoặc empty()
|
|
trước khi chúng được sử dụng.
|
|
<li class="spaced">
|
|
Tẩt cả các xâu nên có thể dịch được -
|
|
tạo các text mới trong các file "lang/en" với các tên
|
|
tiếng Anh chính xác chữ thường và lấy chúng
|
|
từ mã thông qua sử dụng get_string() hoặc
|
|
print_string().
|
|
<li class="spaced">
|
|
Tất cả các file trợ giúp nên có thể dịch
|
|
được - tạo các text mới trong thư mục
|
|
"en/help" và gọi chúng sử dụng helpbutton().
|
|
<p>Nếu bạn cần cập nhật một file trợ
|
|
giúp:
|
|
<ul>
|
|
<li>
|
|
với một sự thay đổi nhỏ, nơi mà
|
|
bản dịch cũ của file vẫn có ý nghĩa, thì có
|
|
thể thực hiện thay đổi trên bản dịch
|
|
cũ nhưng phải thông báo cho translation@moodle.org
|
|
<li>
|
|
với một sự thay đổi lớn bạn nên
|
|
tạo một file mới bằng cách đưa vào một
|
|
số tăng (ví dụ filename2.html) sao cho các người
|
|
dịch có thể dễ dàng nhìn thấy phiên bản mới
|
|
của file. Hiển nhiên mã mới và các chỉ sổ file
|
|
trợ giúp nên được thay đổi để
|
|
chỉ ra phiên tới phiên bản mới nhất.</li>
|
|
</ul>
|
|
<P></P>
|
|
<li class="spaced">
|
|
Các dữ liệu đến từ trình duyệt
|
|
(được gửi thông qua GET hoặc POST) tự
|
|
động được xử lý bằng magic_quotes (không
|
|
quan tâm tới việc thiết lập trong PHP) sao cho
|
|
bạn có thể chèn chúng an toàn vào cơ sở dữ
|
|
liệu. Tất cả các dữ liệu thô khác (từ các
|
|
files, hoặc từ các cơ sở dữ liệu) phải
|
|
được thoát bởi <font color="#339900">addslashes()</font>
|
|
trước khi chèn nó vào cơ sở dữ liệu.
|
|
<li class="spaced">
|
|
QUAN TRỌNG: Mọi text bên trong Moodle, đặc biệt là
|
|
xuất phát từ người dùng, sẽ được
|
|
in sử dụng hàm format_text(). Điều này đảm
|
|
bảo rằng text được lọc và xoá theo đúng
|
|
cách.</li>
|
|
</ol>
|
|
<p> </p>
|
|
<h2>Phong cách coding</h2>
|
|
<p class="normaltext">Tôi biết có thể khó chịu cho bạn khi
|
|
thay đổi phong cách nếu bạn đã quen với cái
|
|
gì đó, nhưng bù lại mọi người sau này sẽ
|
|
dễ tiếp cận với mã. Hiển nhiên có nhiều lí
|
|
do mà mọi người nên theo một phong cách viết mã
|
|
thống nhất , chúng sẽ được quy
|
|
định dưới đây <strong>như sau</strong>, xin hãy
|
|
tuân thủ theo nó.
|
|
</p>
|
|
<ol class="normaltext">
|
|
<li class="spaced">
|
|
<strong>Indenting</strong>
|
|
nên là 4 khoảng trống một cách nhất quán. Đừng dùng các tab.
|
|
<li class="spaced">
|
|
<strong>Các tên biến</strong> nên dễ đọc, có ý nghĩa
|
|
là các từ tiếng Anh thấp. Nếu bạn cần nhiều hơn một từ thì hãy dùng chúng
|
|
với nhau, nhưng giữ chúng càng ngắn càng tốt. Dùng các tên số nhiều cho các dãy
|
|
đối tượng.
|
|
<p class="examplecode"><font color="#006600">TỐT: $quiz<br>
|
|
TỐT: $errorstring<br>
|
|
TỐT: $assignments (for an array of objects)<br>
|
|
TỐT: $i (but only in little loops)<br>
|
|
<br>
|
|
TỒI: $Quiz
|
|
<br>
|
|
TỒI: $aReallyLongVariableNameWithoutAGoodReason<br>
|
|
TỒI: $error_string</font></p>
|
|
<li class="spaced">
|
|
<strong>Các hằng số</strong> nên là các chữ hoa, và luôn bắt đầu bằng
|
|
tên các module. Chúng là các từ được phân cách với nhau bằng dấu gạch chân.
|
|
<p class="examplecode"><font color="#006600">define("FORUM_MODE_FLATOLDEST", 1);</font></p>
|
|
<li class="spaced">
|
|
<strong>Tên các hàm</strong> nên là các từ tiếng Anh bình thường, và
|
|
bắt đầu bằng tên module để tránh xung đột với các module. Các từ
|
|
phải được phân cách bằng dấu gạch chân. Các tham số nên được đặt một cách
|
|
cẩn thận nếu có thể. Chú ý không có khoảng trống giữa tên hàm và
|
|
các dấu ngoặc như dưới đây.
|
|
<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 class="spaced">
|
|
<strong>Các khối</strong> luôn luôn được đóng bởi các ngoặc nhọn (thậm chí nếu
|
|
chỉ có một dòng). Moodle sử dụng style dưới đây:
|
|
<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 class="spaced">
|
|
<strong>Các chuỗi</strong> nên được định nghĩa sử dụng các dấu nháy đơn khi mà có thể,
|
|
để tăng tốc độ.<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>
|
|
|
|
<strong>
|
|
<li class="spaced">
|
|
<strong>Các chú thích</strong> nên được đưa vào càng nhiều càng tốt là rất thực tế, to giúp
|
|
giải thích mã và mục đích của các hàm và các biến.
|
|
<ul>
|
|
<li>
|
|
Mỗi hàm (và lớp) nên dùng <a target="_blank" href="http://www.phpdoc.org/">
|
|
định dạng phpDoc</a>. Điều này cho phép tài liệu mã được sinh
|
|
tự động.</li>
|
|
<li>
|
|
Các chú thích inline nên sử dụng phong cách //, được trình bày gọn gàng sao cho nó thích hợp
|
|
với mã và đưa ra các dòng riêng cho nó.</li>
|
|
</ul>
|
|
<p class="examplecode"><font color="#FF8000"> /**<br />
|
|
* Mô tả nên đặt đầu, với dấu * được đặt chính xác<br />
|
|
* như ví dụ này. Nếu bạn muốn tham chiếu tới các hàm khác,<br />
|
|
* thì hãy dùng: {@link clean_param()}. Sau đó, đưa các mô tả
|
|
<br />
|
|
* cho mỗi tham số như sau.<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">
|
|
Khoảng trống</strong> nên được sử dụng tự do - đừng ngại mở rộng
|
|
thêm để bù lại chúng ta sẽ được sự rõ ràng hơn. Nói chung, nên có một khoảng trống giữa các
|
|
dấu ngoặc và các statement bình thường, nhưng không có khoảng trống giữa các dấu ngoặc và các biến hoặc
|
|
các hàm:<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>Cấu trúc cơ sở dữ liệu</h2>
|
|
<ol class="normaltext">
|
|
<li class="spaced">
|
|
Mọi bảng phải có một <strong>id</strong> tự tăng
|
|
như là một trường (INT10) là index chính.
|
|
<li class="spaced">
|
|
Bảng chính chứa các instance của mỗi module phải có tên trùng với
|
|
tên module (ví dụ <strong>widget</strong>) và chứa tối thiểu các trường sau
|
|
:
|
|
<ul>
|
|
<li>
|
|
<strong>id</strong>
|
|
- như mô tả ở trên
|
|
<li>
|
|
<strong>course</strong>
|
|
- id của cua học mà mỗi instance thuộc về
|
|
<li>
|
|
<strong>name</strong> - tên đầy đủ của mỗi instance của module</li>
|
|
</ul>
|
|
<li class="spaced">
|
|
Các bảng khác gắn liền với một module chứa các thông tin về 'things'
|
|
nên được đặt tên là <strong>widget_things</strong>
|
|
(chú ý về số nhiều).
|
|
<li class="spaced">
|
|
Các tên cột phải đơn giản và ngắn gọn, hãy tuân theo các luật giống như
|
|
tên các biến.
|
|
<li class="spaced">
|
|
Khi có thể, các cột chứa một tham chiếu tới trường id của bảng khác
|
|
(ví dụ <strong>widget</strong>) nên được gọi là <strong>widgetid</strong>.
|
|
(Chú ý rằng các quy ước này mới và không được tuân theo ở một số bảng cũ)
|
|
<li class="spaced">
|
|
Các trường boolean nên được thực thi như là các trường số nguyên nhỏ (eg INT4)
|
|
chứa 0 hoặc 1, cho phép mở rộng sau này khi cần thiết.
|
|
<li class="spaced">
|
|
Đa số các bảng phải có trường <strong>timemodified</strong> (INT10) được
|
|
cập nhật với timestamp hiện thời lấy được thông qua hàm <strong>time</strong>()
|
|
của PHP.</li>
|
|
</ol>
|
|
<hr>
|
|
<p align="center"><font size="1"><a href="." target="_top">Tài liệu của Moodle</a></font></p>
|
|
<p align="center"><font size="1">Version: $Id: coding.html,v 1.1 2005/03/20 22:55:53
|
|
koenr Exp $</font></p>
|
|
</body>
|
|
</html>
|