| 程序员指南 | |
|---|---|
| Help developers to navigate | |
| Keywords | |
| Table of Contents | |
希望支持Semantic MediaWiki开发或者开发SMW扩展的开发人员可以利用许多资源来着手开始。 当然，强烈建议同时对SMW的使用方法也加以熟悉。 再者，从开发人员的角度上，还有一份SMW系统架构指南（英文版），对SMW当中的主要思想和概念做了基本的介绍；在阅读和编写SMW相关代码的时候，这份指南应当有所帮助。
所有希望为SMW贡献代码的开发人员均应当仔细阅读本页面。
着手开始[edit]
SMW系统架构指南（英文版），从开发人员的角度，对SMW当中的主要思想和概念做了基本的介绍。
当从SMW用户转变成为SMW开发人员的时候，您也应当更改自己的测试用维基站点的配置， 以便确保您不会遗漏掉可能出现的错误或问题（尤其是您自己的代码所造成的那些）。 请您阅读关于如何调试MediaWiki的方法，尤其是关于PHP错误报告的章节。 所有的MediaWiki扩展预期在运行时都不会发出任何的PHP通知！
同时，也请您花点时间熟悉一下适合于开发人员的MediaWiki资源。
代码文档记录[edit]
SMW及其扩展都在努力提供完整的代码文档，作为其程序文件的组成部分。API文档是依据下列数据自动生成的：
这份文档记录涵盖SMW、语义结果格式（Semantic Result Formats）、语义表单（Semantic Forms）、语义钻取（Semantic Drilldown）以及语义地图（Semantic Maps）。它是利用SVN的最新内容每天自动重新构建的。进一步的扩展如果与SMW相关，亦可添加到这份文档当中，并托管在MediaWiki SVN之中，而且为了防止与其余的扩展之间发生混淆，还使用命名惯例（不同的扩展采用的前缀分别为SMW、SRF、SF、SD和SM）。
要快速概览SMW当中的代码分布情况，可以查看如下页面：
安全方面[edit]
拥有开放用户社区的网络应用程序尤其易于遭受安全漏洞的威胁。 SMW开发人员负责专门照顾安全问题，以避免所有种类的漏洞。 每位开发人员都应当仔细阅读适合于开发人员的MediaWiki安全指导原则。
一旦发现漏洞，就需要给予特别关照，尽可能降低这些漏洞被利用的风险。 尤其是，明智的做法就是首先直接联系核心开发人员（比如，给Markus Krötzsch发电子邮件），以便在该错误公开之前，能够发布经过更新的版本。 同时，也请注意，本项目的SVN是公开的，因而也可能处在潜在攻击者的监视之下。 因此，提交诸如"Fixed critical security vulnerability"（修复了重要的安全漏洞）之类的消息也可能成问题。 关于开源软件安全问题处理的详情，请参见这里。
将代码或补丁提交至SVN[edit]
任何向SVN提交代码的人员，不论其是否是最初编写这些代码的人员，均负有核查这些代码是否符合本页面所列指导原则的特别责任。 在提交代码之前，请核对下列事项：
- 提交者已经阅读过这些代码，并且发现这些代码易于阅读和易于理解。
- 提交者已经核实过，这些代码是安全的。尤其是检查过，没有在HTML或SQL当中使用任何用户所录入的，未经正确转义的数据（参见上面所提及的MediaWiki安全指导原则）。
- 提交者已经针对是否这些代码的确如期有效运行，对这些代码进行过测试。对于让这些代码有其功用的每项功能特性或错误修复方法，必须至少采用一个示例检查过。如果这些代码当中包括配置（英文版）选项，针对其是否能够正确发挥作用，也必须加以测试。
再次强调的是：向SVN提交代码的人员必须亲自阅读过且测试过所有的代码。 亦可在几位予以许可的SMW开发人员当中分配这些任务，但最终的责任始终归于提交代码的人员。 对于那些来自于Bugzilla或电子邮件的代码，这一点尤为重要。 必须将此类来源的代码视为未经审核且未经测试的代码。 当然，如果贡献者富有经验的话，代码将会易于阅读且具有完备的文档记录，从而留给提交者的工作就会很少。 为了改进代码，应当向贡献者指出本页面所在，以便他们可以加快其贡献过程。
改进您的编程/测试环境[edit]
采取有助于迅速发现和追踪问题的方式来设置本地的维基站点安装包，乃是有益的做法。 另一方面，采用不太常见的设置也是有用的，以确保可以在某种程度上对这些设置也加以测试：
- 在安装MediaWiki的时候，请使用一个非空的DB table prefix（数据库表前缀）。
- 在您的LocalSettings.php当中，使用$wgArticlePath = "$wgScript?title=$1";（CGI兼容模式）。也可以来回变更，以便利用您的代码对两种式样的URIs都加以测试。
- 此外，在您的LocalSettings.php当中，激活$wgShowSQLErrors = true; 和 $wgDebugDumpSql = true;。
另一方面，一些PHP专用设置有利于找出代码问题：
- 在INSTALL当中发现所需版本的PHP。
- 所有开发人员都需要打开PHP当中的所有的错误、警告和通知。编辑您的文件php.ini，在其中包括语句error_reporting = E_ALL，并且删除任何其他此类的语句。
- 编辑您的文件php.ini，在其中包括语句allow_call_time_pass_reference = Off。
- 您的最终代码绝不应当创建任何相应的消息。
- 打开您的PHP的xdebug，以便改善错误报告的细节（xdebug实际的个人设置<profiling>功能并不一定为此而被打开）。
编程风格[edit]
SMW及其许多的扩展都坚持着严格的命名惯例和代码样式。 这些命名惯例和代码样式依据的是MediaWiki代码编写惯例。 下列指导原则适合于SMW，但常常还可以用于其他的扩展，而只是更改前缀SMW即可。
文件与文件夹[edit]
- 项目之中的文件全都加以前缀"SMW_"。一般来说，应当有可能在不发生名称冲突的情况下，将所有的项目文件都放在MediaWiki的include文件夹当中。
- 通常并不更改或创建文件夹。唯一的例外就是特殊页面（Special pages）；这些页面全都位于"specials"文件夹之下各自的文件夹当中。
编码[edit]
- 所有的文件均需要存储为UTF8编码格式！这一点绝对是至关重要的！
- 所有的行结尾必须采用UNIX风格。设置您自己的auto-props（自动属性设置）！
PHP[edit]
- 请勿在您的源文件当中使用结束标签"?>"。这是所包含文件当中并不需要的一个错误来源。
命名惯例[edit]
尽管方法名称（methodNames）和变量名称（variableNames）通常以小写字母开头，但一般来说，所有的名称均采用驼峰式大小写（CamelCase）。
- 可全局访问的类均采用前缀"SMW"。封装在方法之中的类定义并没有前缀。另一个例外情况就是Specials的类；就像MediaWiki当中常见的那样，应当根据特殊的类加以命名（原文：Another exception are classes for Specials which should be named after the special, as is common in MediaWiki.）。
- 可全局访问的函数均采用前缀"smwf"。类函数（Class functions）没有专门的前缀。
- 全局声明的变量均采用前缀"smwg"。函数当中的局部变量通常不采用驼峰式大小写，但如果需要任何分隔时，则采用"_"。
- 常量采用全部大写字母形式，以下划线为内部分隔符，并且要加以前缀"SMW_"，如在"define('SMW_SP_HAS_TYPE', 1)"当中。
代码布局与缩进[edit]
一般来说，代码布局遵循MediaWiki代码编写惯例。请务必阅读该文档。
- 对您的所有代码均加以文档记录（详情请参见下文）！
- 避免单行代码变得过长。
- 程序代码块的缩进采用制表符，而不是空格。所有的程序代码块均要缩进。
- 所有缩进的程序代码块均应当采用花括号“{”和“}”括起来，即使只有一行。
- 可以采用嵌入式条件语句（in-line conditionals）来计算取值("condition?thenvalue:elsevalue")。
- 建议在"="（变量赋值符号）以及所有的操作符两侧，包括"."（字符串串联符号在内），使用空格。
- 在条件语句中，合取（conjunctions）和析取（disjunctions）应分别写作&&和||，而不是and和or。
- true、false和null之类的常量值始终采用小写形式。
- 在适合的情况下，应当将类成员声明为protected（保护型）或private（私有型）。不要求使用public（公有型），因为它是默认类型（对于变量而言则有所不同，public的使用优先于var）。
- 在合适的情况下使用关键词static（静态）。请考虑把全局函数变为静态 类 函数（static class functions）。
- 当完成某项任务时，请花些时间从您的代码当中清除未使用的调试语句、函数以及局部变量！
JavaScript[edit]
命名惯例[edit]
尽管方法名称（methodNames）和变量名称（variableNames）通常以小写字母开头，但一般来说，所有的名称均采用驼峰式大小写（CamelCase）。
- 函数均采用前缀"smw_"。
- 变量大多数并不遵循任何的命名惯例，但全局变量则应当采用前缀"smw_"。
代码布局与缩进[edit]
目前，对于SMW的JavaScript，尚未提出或实施任何通用的代码布局。
文档记录[edit]
在90%的时间里，SVN必须都是可部署的。根据需要，请随时更新INSTALL（安装）！当出现不兼容型变更的时候，请提供更新说明和方法。
- 每个类和函数都必须备有简短的文档记录，并采用"/** ... */"将其括起来。这些注释块将用来借助于doxygen而生成MediaWiki代码文档。
- 尽可能采用 @since 来表示添加相应函数或字段时的版本。对于钩子（hooks），做法也是如此。
- 尽可能采用类型提示（type hinting）。在可能被继承的新代码当中，这么做具有重要作用，因为当基础类（base class）当中没有这么做的话，其派生类（deriving classes）就无法使用类型提示。
- 在doxygen注释当中使用 "@todo"和"@bug"，以便直接在代码里面追踪待办事项（to-dos）和错误。
- 应当采用C语言式行注释（"// ..."），对复杂的代码和hacks（整修之处）加以文档记录。
- 应当采用Shell式行注释（"# ..."），对用户文档（大多数是关于SMW_Settings.php的）加以记录。
- 在发布之前，必须在在线用户文档（英文版页面）之中对影响使用的实施加以文档记录。
- 在发布说明RELEASE-NOTES文件之中，必须提及那些与用户、管理员或第三方开发人员相关的变更。简短的说明足矣。
创建结果格式[edit]
关于如何创建结果格式，请参见这个页面（英文版）。
获得支持[edit]
SMW项目欢迎所有潜在的贡献者和扩展开发人员。 开发人员可在SMW开发人员邮件列表之上开展讨论；可以利用该列表来联系SMW核心开发人员。 SMW项目欢迎借助MediaZilla报告错误；亦可将其用于功能特性请求。
也可能有现成的商业化支持、定制开发项目以及培训活动（取决于您的实际位置和项目规范书）– 详情请联系Markus Krötzsch。
测试[edit]
SMW系统测试[edit]
SMW单元测试[edit]
- 目前还没有指导原则。不过，为了获得高质量的代码，还是强烈建议进行SMW单元测试（比如， 采用PHPUnit）。
