Qomo项目中代码的一般性约定

================================================================================
Qomolangma OpenProject v1.0

类别 ：Rich Web Client
关键词 ：JS OOP，JS Framwork, Rich Web Client，RIA，Web Component，
DOM，DTHML，CSS，JavaScript，JScript

项目发起：aimingoo ([e-mail])
项目团队：..\..\Qomo_team.txt
================================================================================

一、变量声明的一般性方法
~~~~~~~~~~~~~~~~~~
Qomo约定在全局空间进行变量声明时，应用var关键字来声明，而不应当省略(尽管语法上讲能这样做)。
声明时的代码格式尽可能使用如下形式：
------------------
var
v1 = 1234;
v2 = 'abcd';
------------------
或为每行声明都保留var关键字，例如：
------------------
var v1 = 1234;
var v2 = 'abcd';
------------------

Qomo约定在函数内部声明局部变量进，使用var关键字时可以用如下省写形式：
------------------
var
v1 = 1234, // <-- 注意行未是逗号
v2 = 'abcd';
------------------
或为每行声明保留var关键字。

Qomo反对在函数内部声明全局变量。

二、Qomo中一些保留的命名
~~~~~~~~~~~~~~~~~~
Qomo会将一些实现特殊的、具有“关键字”性质的功能声明为全局函数。它们通常具有特殊的名字，而且
是以大写字符开始的(这看起来有点象构造器，但并不是)。这些函数名部分看起来象JavaScript的保留字，
但由于javascript的命名是大小写区分的，且保留字都使用小写字符，因此这并不冲突。这些全局函数有：
------------------
Class() : 注册类
Attribute() : 快速属性声明
Interface() : 接口声明
Aggregate() : 接口聚合
Abstract() : 抽象方法
NullFunction() : 空函数／空方法
------------------

Qomo为构建系统框架，使用标准的JS原型继承的方式在全局范围内声明了一些类(构造器)，用户代码应该
避免覆盖这些名称。这些命名包括：
------------------
Url() : 分析一个Url地址
Ajax() : Ajax异步方式
MuEvent() : 多投事件
CustomArguments() : 标识函数入口使用了定制参数
BreakEventCast() : 标识事件投送列表被中止
JoPoint() : 切面系统中的连接点
JoPoints() : 切面系统中的连接点列表
Profilers() : 创建系统分析对象
------------------

作为习惯，Qomo保留了一些(少量的)全局的工具函数，例如：
------------------
format() : 指向String.format();
RegisterInterface() : 指向Interface.RegisterInterface()
QueryInterface() : 指向Interface.QueryInterface()

isAlias() : 检测一个命名空间是否是别名
isNamespace() : 检测一个变量是否是命名空间声明

getAllFunctions() : (用于调试与性能分析,) 列出一个代码块中调用过的函数与方法
showProfiler() : (用于调试与性能分析,) 调用$debug来显示性能分析报告
------------------

除了上述三种情况，Qomo中将尽可能少的占用全局的命名，例如函数或变量。

为此，Qomo为开发人员准备了一份资料文档，用于通告哪那些全局函数、类与命名空间被使用了，开发
人员应尽可能避免出现相冲突的命名。

三、Qomo中的一些命名约定
~~~~~~~~~~~~~~~~~~
1. 系统的特殊声明
==============
Qomo约定以$开始的变量为系统特殊的声明，它通常是关键的函数或可能在系统编译时被特殊处
理的函数。这些函数主要包括：
------------------
$import() : 导入文件或包
$inline() : 内联代码块
$assert() : 断言
$debug() : 调试输出

$map() : 创建命名与路径的映射
$mapx() : 展开命名空间
$n2p() : 命名空间到路径的转换
$p2n() : 路径到命名空间的转换

$profilers : (对象)全局的性能分析器

$Q() : 等同于$QomoConfig
$QomoConfig() : 查询Qomo装载时或编译时的配置信息
$QomoCoreFunction : 简单地返回一个函数用来替换Function对象的toString()方法，以保护代码
------------------
此外，一些函数内的局部变量也使用$来表明它的特殊性。

Qomo约定以"_"开始的函数具有使用的上下文环境限制。主要包括：
------------------
// 以下函数仅能在类声明中使用
// - 注: Attribute()也仅能在类声明使用
_cls : 取类引用
_get : 类内部信息的getter
_set : 类内部信息的setter
------------------
此外，一些函数内的局部变量也使用_来表明它的特殊性，或与一个没有该前缀的同名函数存在关联。

Qomo约定全大写的变量是系统保留的，或有特殊的含义的变量，该规则并不限于在函数内／外使
用。例如：
------------------
_RTLOBJECT : 在Qomo替换之前的Object()构造器
_RTLERROR : 在Qomo替换之前的Error()构造器
------------------

2. 异常
==============
Qomo约定以字符“E”开始并紧邻一个大写字母表明一个异常。异常可以用数组形式来表示，例如：
------------------
ECallClassBadArguments = [8101, 'Arguments error for Class().'];
ERegClassNoname = [8102, 'With call Class(), lost class name .'];
EAccessSafeArea = [8104, 'Try Access Safe area.'];
------------------

3. 类与类类型注册
==============
Qomo约定以大写字母开始的函数通常是类构造器，而以小写字母开始的函数是普通函数或方法。这
一点是JavaScript惯用的代码风格。例如：
------------------
// 类构造器
function MyObject() {
// ..
}

// 方法或函数
function callSafeMethod() {
// ..
}
------------------

Qomo约定应当以字符“T”开始，后面紧跟构造器函数名的格式对一个类进行类注册。Qomo的OOP系统和命
名空间系统依赖于类注册。类注册使用Class()函数。例如：
------------------
// 类构造器声明
function MyObject() {
// ...
}

// 类注册
TMyObject = Class(Object, 'MyObject');
------------------

4. 事件、事件句柄与事件类型
==============
Qomo约定以On开始的属性为事件，而以do开始的函数通常用作事件句柄。例如：
------------------
function doCall() {
// ...
}

function MyObject() {
this.OnCall = NullFunction;
}

var obj = new MyObject();
obj.OnCall.add(doCall);
------------------

Qomo约定事件可以用一个函数声明来描述事件的接口，但这个声明除了便于开发人员使用之外，并没有
任何价值。一般情况下，该声明应该以字符“T”起始，紧接事件名，最后可以用Event结束。例如：
------------------
TOnCall = function(item, index) { }
TOnLoadEvent = function(filename, filenum) { }

function MyObject() {
this.OnCall = TOnCall;
this.OnLoad = TOnLoadEvent;
}
------------------
对于上面的声明来说，OnCall与OnLoad后面是一个空函数(NullFunction)还是一个事件类型的声明并没有
关系。上面这样做，只是便于开发人员理解：当事件发生时，事件句柄可以得到怎样的入口数据。

由于“事件类型”只有声明和描述的价值，它事实上从来不会被执行。因此，可以在不同的文件中，或者
相同文件的不同类、不同位置重复的声明相同名字的“事件类型”。这对程序执行不会有负面的影响。

5. 接口
==============
Qomo约定接口是以“I”字符开始来声明一个函数。接口的方法应声明为Abstract。例如：
------------------
IInterface = function() {
this.QueryInterface = Abstract;
}
------------------

6. 切面
==============
Qomo约定应尽量以asp或asp_为前缀来声明切面。例如：
------------------
var asp_OnTimer = new ObjectAspect(T2, 'OnTimer', 'Event', x0);
var asp_getTopoString = new FunctionAspect(getTopoString, 'getTopoString', 'Function');
------------------

7. 内联代码
==============
使用$inline()可以将一个代码片断内联到当前位置执行。Qomo约定被联接的代码块应该是一个独立的
文件，文件中可以包括注释，其代码体应该被包含在一个标签声明当中。这个标签声明只用于表现该
代码块的特殊性，实际上没有执行价值。

该标签声明应当以“_inline_”为前缀。例如：
------------------
/**
*
* 内联代码可以按JS的语言规范任意包含注释
*
*/
_inline_object_regAllInterfaceForClass: {

// register interfaces for Class's all instnaces
if (arguments.length > 2) {
Interface.RegisterInterface.apply(cls, [cls].concat(
Array.prototype.slice.call(arguments, 2)
))
}

}
------------------

8. 字符串、数组、正则等使用中的一般性规则
==============
Qomo约定尽可能以单引号来声明字符串，而将双引号留给HTML中的属性来使用。

Qomo约定以如果在全局使用正则表达式，应该以“_r_”为前缀声明，在函数局部使用正则表达式，应
尽可能使用该规则。例如：
------------------
_r_event = /^On.+/;
_r_attribute = /^([gs]et)(.+)/;
------------------

JavaScript中常用数组来表达一张表格，Qomo建议这种情况下的代码应该写成如下格式：
------------------
var aTable = [
[v1, v2, v3, v4],
[v1, v2, v3, v4],
[v1, v2, this_is_long_variant, v4],
[v1, v2, v3, v4] // <-- 注意最后一行没有","号
];
------------------
尽可能用对齐的方式来避免表格修改时导致的出错。

四、Qomo中的一些特殊使用法
~~~~~~~~~~~~~~~~~~
1. 对象(Object)的特殊用法
==============
Qomo直接替换了构造器Object()，因此使用new Object()的方式会构造出一个Qomo格式的对象实例。
但用户代码中仍然可以通过直接量声明来得到一个“原生的”JavaScript对象。例如：
------------------
var
obj_1 = new Object(); // Qomo对象
obj_2 = { }; // JavaScript原生的、直接量声明的对象
------------------
二者的区别在于，obj_1因为是Qomo对象，因此必然具有如下方法和属性：
------------------
obj_1.ClassInfo
obj_1.get()
obj_1.set()
obj_1.inherited()
------------------
而obj_2由于是原生的JavaScript对象，因此使用for .. in来列举时，不会看到任何“显式的”
属性与方法。

Qomo约定用户代码不应当修改直接量形式所得到的Object的原型(prototype)。由于这种对象没有任
何“显式的”属性与方法，因此它可以用来做for .. in做一些高速的列表处理。部分内核代码使用
了这种特性。

——在firefox等mozilla引擎中，对替换后的Object()进行原型修改会污染(我并不确定这是否更加
规范)原生的、直接量声明的对象。因此本项“特殊用法”应当谨慎使用。

10. 匿名函数的特殊使用法
==============
为了避免一段代码占用全局空间中的名称（命名污染），通常会使用匿名函数来执行一段代码。Qomo
建议这种情况下使用void来触发该匿名函数的执行。——而不是使用一对括号来做相同的事。例如：
------------------
// 推荐用法
void function() {
// 你的代码...
}();

// 不推荐用法
(function() {
// 你的代码...
})();
------------------

如果执行的结果会返回值，例如声明一个变量。则建议使用如下的结构：
------------------
var myFunc = function() {
// 一些私有变量的声明
var ...

// 你的函数
var _myFunc = function() {
//...
}

// 返回
return _myFunc;
}();
------------------

如果不对上述的_myFunc做特殊处理(例如添加属性)，那么上述的代码可以简化至：
------------------
var myFunc = function() {
// 一些私有变量的声明
var ...

// 返回你的函数
return function() {
//...
}
}();
------------------