Moodle 项目帮助手册:程序编写准则

  • 403 views
Uploaded on

Moodle 项目帮助手册:程序编写准则

Moodle 项目帮助手册:程序编写准则

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
403
On Slideshare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
1
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. Moodle 项目帮助手册:程序编写准则 OSS 计算技术 - http://www.ossez.com 1 of 6 Moodle程序编写准则 任何合作的项目都需要一致性和稳定性才能保持它的强壮。 编写这些准则的目的是为所有的Moodle代码提供一个努力的目标。有一些比较老的已经存在的 代码在极少的方面尚未达标,但它们最终将会被修正。所有新的代码都必须尽可能地遵守这些准 则。 一般规定 1. 所有代码文件应当使用 .php 作为扩展名。 2. 所有模板文件应当使用 .html 作为扩展名。 3. 所有文本文件应当使用Unix风格的文本格式(多数的文本编辑器都有这个选项)。 4. 所有php标记都必须是“完整”标记,譬如<?php ?> ... 而不是如<? ?>的“短”标记。 5. 所有已经存在的版权声明应当被保留。如果有必要,您可以加入自己的。 6. 每个文件都应当包含主config.php文件。 7. 每个文件都应当检查用户的身份是否正确,可以使用函数require_login()和isadmin()、 isteacher()、iscreator()或者isstudent()。 8. 所有访问数据库的操作都应当使用lib/datalib.php中的函数――这样可以兼容更多的数据库 服务器。所有的事情都应当是可以用这些函数来完成的,如果遇到必须要写SQL代码的情 况,请记住这些代码应当是跨平台的,且仅仅对您代码中的特定函数(通常在一个lib.php文 件中)有效,且代码中用注释进行明确说明。 9. 不要建立和使用标准全局变量$CFG、$SESSION、$THEME和$USER之外的全局变量。 10. 所有变量都应当被初始化或者至少在使用前用isset()或empty()等函数进行检测。 11. 所有字符串都应当可翻译――在"lang/en"目录中创建新的文本文件,字符串应当使用简洁 的英文小写名称,并通过函数get_string()或print_string()来取得。 12. 所有帮助文件应当可翻译――在"en/help"目录中创建文本文件并且通过helpbutton()函数来 调用它们。1 of 6 2012-09-29 01:44
  • 2. Moodle 项目帮助手册:程序编写准则 OSS 计算技术 - http://www.ossez.com 2 of 6 如果需要上传一个帮助文件: 对于小的修改,旧的翻译文件仍然可以继续使用时,可以直接进行修改,但您应当通 知translation@moodle.org 对于大的修改,应当创建新的文件,新文件的文件名是在原文件名的末尾添加一个数 字,并在以后逐渐增加(如filename2.html),这样翻译人员就可以方便地知道文件有 了一个新的版本。很显然,新的代码和帮助索引文件都必须修改以指向新版本的文 件。 13. 从浏览器发来的信息(以GET或POST形式发送)都应用了magic_quotes(无论PHP的设置如 何),因此直接将它们插入到数据库中是安全的。所有其它的原始数据(来自文件或数据库 的)都必须在插入数据库前使用addslashes()进行预处理。 14. 重要的:Moodle中所有的文本,特别是用户提供的文本,都必须使用format_text()函数来 输出。这样就可以确保文本已经正确地过滤。 编码风格 我知道,如果您已经习惯了一种编码风格而我却让您改变它是有一点讨厌的,但比较而言,这比 日后所有人都需要去搞清混合风格的Moodle代码要好一些。对于人们使用的任何编码风格都有 很多支持和反对的意见,但现在正在使用的风格已经存在了,因此请坚持下去。 1. 缩进应当是4个连续的空格。绝对不要使用制表符。 2. 变量名应当是容易理解、有含义的小写英文单词。如果确实需要两个或以上的单词,请把 它们连在一起,但要保持名称尽可能短。对于数组对象,请使用复数名称。 好的: $quiz 好的: $errorstring 好的: $assignments (用于数组) 好的: $i (仅用于小型循环) 坏的: $Quiz 坏的: $aReallyLongVariableNameWithoutAGoodReason 坏的: $error_string 3. 常量应当总是大写的,并总是以模块的名称作为前缀。单词之间应当用下划线分隔。 define("FORUM_MODE_FLATOLDEST", 1); 4. 函数名称应当是简单的英文小写单词,且总是以模块名作为前缀以防止模块之间的冲突。 单词之间以下划线分隔。变量如果可能应当总有合理的缺省值。注意在函数名和其后的括2 of 6 2012-09-29 01:44
  • 3. Moodle 项目帮助手册:程序编写准则 OSS 计算技术 - http://www.ossez.com 3 of 6 号之间没有空格。 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. 语句块必须总是使用大括号(即便是只有一行)。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格式编写,以便自动生成代码文档。 内嵌注释应使用 // 风格,并且整齐布局,使其能融入代码中并和代码对齐。 /** * 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 array3 of 6 2012-09-29 01:44
  • 4. Moodle 项目帮助手册:程序编写准则 OSS 计算技术 - http://www.ossez.com 4 of 6 if ($rates = get_records("forum_ratings", "post", $postid)) { // Process each rating in turn foreach ($rates as $rate) { ....etc 8. 换行可以被大方地使用——把东西分散开看起来会比较清楚。一般情况下,在花括号和普通 命令之间应当有一个换行符,但在花括号和变量或函数之间可以没有换行符: foreach ($objects as $key => $thing) { process($thing); } if ($x == $y) { $a = $b; } else if ($x == $z) { $a = $c; } else { $a = $d; } 数据库结构 1. 每个表格都必须有一个自增的id字段(INT10)作为主键。 2. 包含着模块中数据实例的主表格必须和模块同名(譬如widget),并且至少包含如下字段: id - 如上一条所述 course - 每个实例所属的课程id name - 每个实例的完整名称 3. 与模块相关的其它表格的命名规则是:如果它包含的信息是关于“things”的,则它的名字 应当是widget_things(注意采用复数形式)。 4. 字段名称应当简短,与变量名的规则相同。 5. 在可能的情况下,包含着对其它表格(如widget)引用的字段应当命名为widgetid。(注意这 是个新约定,有一些老的表格并未遵守) 6. 布尔字段应当使用小整数类型(如INT4)并存储为0或1,这样就可以在需要时扩展它。 7. 多数的表格应当有一个timemodified字段(INT10),并用PHP的time()函数取得的当前时间 戳来更新它。4 of 6 2012-09-29 01:44
  • 5. Moodle 项目帮助手册:程序编写准则 OSS 计算技术 - http://www.ossez.com 5 of 6 安全问题(处理表单和URL数据) 1. 不要依靠“register_globals”。每个变量必须在每个源文件里正确初始化。变量的来源必须 显而易见 2. 初始化所有的数组和对象,即使它是空的。$a = array()或$obj = new stdClass();。 3. 不要使用optional_variable()函数。使用optional_param()函数来替代。根据数据类型选 择正确的PARAM_XXXX值。使用set_default()函数检查和设置变量的可选值。 4. 不要使用require_variable()函数。使用required_param()来替代。根据数据类型选择正 确的PARAM_XXXX值。 5. 不要使用$_GET、$_POST或$_REQUEST。根据您的需要使用更合适的required_param()或 optional_param() 6. 检查一个动作时,不要使用像if (isset($_GET[something]))这样的代码。可以使用诸 如:$something = optional_param( something,,PARAM_ALPHA ),并且用empty()函 数或(如果empty也是一个合法值)isset_param()函数测试 7. 在任何可能的情况下,把您所有的required_param()、optional_param()和其它的变量初 始化一起放在每个文件的开头,这样它们会更容易被找到。 8. 使用“sesskey”机制保护表单处理函数不被攻击。简单示例:当生成表单的时候,要包含 <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />。使用表 单时用if (!confirm_sesskey()) {error(Bad Session Key);}检查。 9. 所有文件名必须用clean_filename()函数“过滤”,但如果已经适当地使用 required_param()或optional_param()做了此项工作,则不必如此 10. 再把任何从数据库读出的数据写回之前,必须先用addslashes()处理。一个完整数据对象 可以用addslashes_object()一次性完全处理完毕。 11. 在任何可能的情况下,存入数据库的数据必须来自POST数据(也就是来自表单的数据), 而不能来自GET数据(也就是来自URL的数据)。 12. 如果能避免的话,不要使用来自$_SERVER的数据。它会给移植性带来问题5 of 6 2012-09-29 01:44
  • 6. Moodle 项目帮助手册:程序编写准则 OSS 计算技术 - http://www.ossez.com 6 of 6 13. 在其它地方没有做的情况下,确保所有写入数据库的数据已经被clean_param 函数处理, 并且针对数据类型,使用了恰当的PARAM_XXXX。 14. 如果您编写了自定义的SQL代码,请确保它是正确的。尤其小心在数值周围不要丢失引 号,这可能会带来SQL“注入”漏洞。 15. 每个文件内都要检查它使用的所有数据(尤其是写到数据库的数据)的合法性。不要期盼 或依赖其它地方已经检查了。 16. 被其它文件包含的代码块应当有确切定义的PHP结构(例如类的声明、函数定义等)——直 接执行的代码块建议使用变量时不要初始化。 OSS 计算技术 YUCHENG HU yucheng.hu@ossez.com 2012年09月28日 Moodle文档 Version: $Id$6 of 6 2012-09-29 01:44