Các hướng dẫn về coding trong Moodle

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.

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.

General Rules

Tất cả các file mã phải sử dụng phần mở rộng .php.
Tất cả các file mẫu phải sử dụng phần mở rộng .html.
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).
Tất cả các thẻ PHP phải là các thẻ 'đầy đủ' giống như <?php ?> ... không phải là các thẻ 'ngắn' giống như <? ?>.
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.
Mỗi file nên gồm file chính config.php.
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().
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.
Đừ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.
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.
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().
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().
Nếu bạn cần cập nhật một file trợ giúp:
- 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
- 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.
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 addslashes() trước khi chèn nó vào cơ sở dữ liệu.
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.

Phong cách coding

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 như sau, xin hãy tuân thủ theo nó.

Indenting nên là 4 khoảng trống một cách nhất quán. Đừng dùng các tab.
Các tên biến 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.
TỐT: $quiz
TỐT: $errorstring
TỐT: $assignments (for an array of objects)
TỐT: $i (but only in little loops)

TỒI: $Quiz
TỒI: $aReallyLongVariableNameWithoutAGoodReason
TỒI: $error_string
Các hằng số 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.
define("FORUM_MODE_FLATOLDEST", 1);
Tên các hàm 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.

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;
    }
}
Các khối 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:
if ($quiz->attempts) {
    if ($numattempts > $quiz->attempts) {
        error($strtoomanyattempts, "view.php?id=$cm->id");
    }
}
Các chuỗi nên được định nghĩa sử dụng các dấu nháy đơn khi mà có thể, để tăng tốc độ.

$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";
Các chú thích 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.

Mỗi hàm (và lớp) nên dùng định dạng phpDoc. Điều này cho phép tài liệu mã được sinh tự động.

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ó.

/**
* Mô tả nên đặt đầu, với dấu * được đặt chính xác
* như ví dụ này. Nếu bạn muốn tham chiếu tới các hàm khác,
* thì hãy dùng: {@link clean_param()}. Sau đó, đưa các mô tả
* cho mỗi tham số như sau.
*
* @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

Khoảng trống 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:

foreach ($objects as $key => $thing) {
    process($thing);
}

if ($x == $y) {
    $a = $b;
} else if ($x == $z) {
    $a = $c;
} else {
    $a = $d;
}

Cấu trúc cơ sở dữ liệu

Mọi bảng phải có một id tự tăng như là một trường (INT10) là index chính.
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ụ widget) và chứa tối thiểu các trường sau :
- id - như mô tả ở trên
- course - id của cua học mà mỗi instance thuộc về
- name - tên đầy đủ của mỗi instance của module
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à widget_things (chú ý về số nhiều).
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.
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ụ widget) nên được gọi là widgetid. (Chú ý rằng các quy ước này mới và không được tuân theo ở một số bảng cũ)
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.
Đa số các bảng phải có trường timemodified (INT10) được cập nhật với timestamp hiện thời lấy được thông qua hàm time() của PHP.

Tài liệu của Moodle

Version: $Id: coding.html,v 1.1 2005/03/20 22:55:53 koenr Exp $