Ext编码规范与注意事项

1 Ext编码规范

编码规范主要包含类名称、变量和方法等的命名规范和代码规范。

1.1 命名规范

俗话说：无规矩不成方圆，良好的命名规范是一个系统、框架所必须具备的。

Ext源码都共用一个统一的命名规范，给它的源码带来了很强的可读性和易理解性。依据Ext的规范，根据定义的类别总结以下规范：

1.1.1 类名称

n 一般情况下，类名称由三部分组成，并采用驼峰命名法；第一部分为大写的命名空间，第二部分为小写的包名，第三部分为大写的类名。如：Ext.grid.Panel，Ext为命名空间，grid为源码所在包名称，Panel为包下的类名称。

当最小包时（类定义在最顶层文件夹里）为特殊情况，此时类名应该紧随命名空间，且两个部分都需大写。如：Ext.Component。

n 类名称仅可包含字母和数字，不要使用中划线和下划线；

如非技术术语中需用到数字，则不推荐使用数字。如MyComponent.util.Base64。

n 非Ext官方源码，不要使用Ext作为顶层的命名空间。

n 命名示例：

n

错误写法	正确写法
Foss.Module.MyDefinedClass	Foss. module. MyDefinedClass
Foss. module. myDefinedClass	Foss. module. MyDefinedClass
Foss. module.MYDefinedClass	Foss. module. MyDefinedClass

1.1.1 方法和变量

n 方法和变量的命名和类名称命名一样，遵循驼峰命名法；仅可包含字母和数字，且非技术术语中，不推荐使用数字。

n 命名示例：

错误写法	正确写法
var HTTPReader	var httpReader
var httpREADER	var httpReader
var the2Chid	var theSecondChid
GetMyData()	getMyData()
getJSONData()	getJsonData()
getXML()	getXml()

1.1.2 属性

n 非静态类的属性，命名规则和变量相同。

n 静态类的属性，属性全部使用大写字母。

示例

Ext.MessageBox.YES = ‘yes’;

Foss.module.MyDefinedClass.PI = ‘3.1415926’;

1.1.3 CSS样式

n CSS样式的名称可包含字母、数字和中划线，且字母全部采用小写，非技术术语，不推荐使用数字。如：.ext-ie6符合规范，ext-grid-2row不符合规范。

n CSS样式的名称结构通常为“前缀-组件-明细”，应遵循符合应用此CSS样式的对象所代表的具体内涵。如：.x-grid-cell，其中x为ext的CSS前缀，grid为此CSS样式应用的对象，cell为此对象的单元格，此样式很清楚表达了它的含义：应用在ext中grid上的单元格样式。

n 非Ext官方CSS样式，不要使用x作为样式前缀。

n 命名示例：

错误写法	正确写法
Foss-Form-Readonly	foss-form-readonly
foss-form-CheckBox-body	foss-form-checkbox-body
foss -row-focus	foss-mygrid-row-focus
x-form-radio-readonly（非Ext官方）	foss-form-radio-readonly

1.1.4 总结

n 类名称、变量、方法和属性的命名必须具备易理解、无歧义、方便阅读等特性。这就要求我们在命名的时候，除满足上述规范外，语义（名称的含义）也需要符合被命名对象具体代表的内涵。

如：getCurrentTime()定义为获取当前时间的方法，通过方法名，可以初步判断该方法的作用，一目了然；不推荐使用getTime()、getNowTime()、getCurrent()等语义模糊、错误的命名方式。

1.1 组件代码结构规范

杂乱无章的代码，总会让我们无阅览的欲望，代码具有良好规范，可以使代码具有良好的可阅读性和可维护性。根据Ext组件的代码，总结以下几点规范：

1.1.1 代码的基本结构为：

n 组件的属性

n 组件的初始化方法

n 组件的方法（有三种类型）

a) 与后台数据交互的方法

b) 供自己内部使用或外部调用的方法

c) 监听事件的处理方法

/** *  标准组件定义方式 */ Ext.define(Foss.example.MyComponent', {         /**          * 组件属性          */         extend: 'Ext.Component',         border: false,         frame: true,         /**          * 初始化话组件          */         initComponent: function(config) {                 var me = this;                 /**                  * 具体实现                  */                 me.callParent(arguments);         },         /**          * 与后台交互数据的方法          */         getData: function() {                 /**                  * 具体实现                  */         },         setData: function() {                 /**                  * 具体实现                  */         },         /**          * 供内部使用或外部调用的方法          */         getProperty: function() {                 /**                  * 具体实现                  */         },         getChild: function() {                 /**                  * 具体实现                  */         },         /**          * 监听事件的处理方法          */         onClick: function() {                 /**                  * 具体实现                  */         },         onBefordLoad: function() {                 /**                  * 具体实现                  */         } });

1.1.2 注意事项：

n initComponent方法的作用是初始化组件，如为组件初始化store、items等。此方法只适应于继承于Ext.Component的组件，它为构造方法中的一个初始化组件的方法，在构造函数中被调用。

n 对于组件（继承于Ext.Component），相对于constructor（构造方法），initComponent的任务就是为初始化组件，更具效率和针对性；两者之间为包含关系（constructor包含initComponent）。

1.2 注意事项1.2.1 模块及其包含子模块的菜单链接命名规范

n 某些模块中还需要细分成如干子模块，例如用户权限模块包含用户、角色、授权等子模块

n 由于模块对应的标签页的渲染对象ID（配置renderTo属性）的命名方式和标签页关闭后进行模块内内存回收的处理，导致模块和子模块的菜单链接（Action的URL）的命名方式必须符合一定的规则

1) 主框架js代码根据菜单树中从后台读取的菜单链接，动态生成标签页和页面渲染对象

2) 标签页关闭后，主框架js代码根据默认菜单链接（Action的URL）的命名规则找到所关闭的模块或者子模块进行内存回收的处理

命名示例

受理约车模块的菜单Action配置：#!acceptbookingcar/index.action

用户权限模块下的角色模块的菜单Action配置：#!authorization/roleIndex.action

用户权限模块下的用户模块的菜单Action配置：#!authorization/userIndex.action

1.2.2 模块中主面板和主工具栏的ID和渲染对象ID的命名规范

n 主面板中ID属性的命名规范必须遵循“前缀_包名-模块名-起始Action名称_后缀”

n 主面板中渲染对象ID的命名规范必须遵循“前缀_包名-模块名-起始Action名称-后缀”

n 主工具栏ID属性的命名规范必须遵循“前缀_包名-模块名-起始Action名称_后缀”

n 主工具栏渲染对象ID的命名规范必须遵循“前缀_包名-模块名-起始Action名称-后缀”：

命名示例

poc包下package模块下的主工具栏ID命名：T_poc-package-index_toolbar

poc包下package模块下的主工具栏渲染对象的ID：T_poc-package-index-body

poc包下package模块下的主面板ID命名：T_poc-package-index_content

poc包下package模块下的主面板渲染对象的ID：T_poc-package-index-body

1.2.3 模块中组件ID的命名方式

n 为快速通过ID辨识出组件，模块中组件的ID命名需遵循统一的规范。

n 模块中组件的ID命名规范为：类名称中点号（.）全部替换成下划线（_），后面加上“_ID”

命名示例

Foss.package.PackageGrid的id属性：Foss_package_PackageGrid_ID

Foss.package.SerialNumberWindow的id属性：Foss_package_SerialNumberWindow_ID

Foss.package.DetailPanel的id属性：Foss_package_DetailPanel_ID

2 Javascript编码规范

Javascript的设计不够严谨，存在缺陷。

遵守良好的Javascript编码规范，可以有效的避免它的缺陷。

2.1 大括号的位置

绝大多数的编程语言，都用大括号表示区块。起首大括号的位置，有许多不同的写法。

一种是起首的大括号另起一行：

block { ... }

另一种是起首大括号跟在关键字的后面：

block { ... }

一般来说，这两种写法都可以接受。

但是，Javascript要使用后一种，因为Javascript会自动添加句末的分号，导致一些难以察觉的错误。

return { key:value; };

代码的原意，是要返回一个对象，但实际上返回的是undefined，因为Javascript自动在return语句后面添加了分号。

为了避免这一类错误，需要写成下面这样：

return { key : value; };

规则1：表示区块起首的大括号，不要另起一行。

2.2 分号

分号表示语句的结束。大多数情况下，如果你省略了句尾的分号，Javascript会自动添加。

var a = 1

等同于

var a = 1;

因此，有人提倡省略句尾的分号。

但麻烦的是，如果下一行的第一个字元（token）是如下这五个字符之一，Javascript将不对上一行句尾添加分号。

圆括号	中括号	斜杠	加号	-减号
（	[	/	+	-

例如：

x = y 　　(function () { … 　　})();

等同于：

x = y(function (){…})();

规则2：不要省略句末的分号。

2.3 圆括号

规则3：调用函数的时候，函数名与左括号之间没有空格。

错误写法	正确写法
foo ();	foo();

规则4：函数名与参数序列之间，没有空格

错误写法	正确写法
function foo (arg) { … };	function foo(arg) { … };

2.4 相等和严格相等

Javascript有两个表示“相等”的运算符：“相等”（==）、“严格相等”（===）。

因为“相等”运算符会自动转换变量类型，造成很多意想不到的情况：

false == 'false' // false

false == '0' // true

规则5：不要使用"相等"（==）运算符，只使用"严格相等"（===）运算符。

2.5 变量声明

Javascript会自动将变量声明“提升”到代码块的头部。

if (!o) { var o = {…}; }

等同于：

var o; if (!o) { o = {…}; }

为了避免可能出现的问题，不如把变量声明都放在代码块的头部。

规则6：所有变量声明都放在函数的头部。

规则7：所有函数都在使用之前定义。

2.6 变量声明

Javascript最大的语法缺点，可能就是全局变量对于任何一个代码块，都是可读可写。这对代码的模块化和重复使用，非常不利。

规则8：避免使用全局变量，如果不得不使用，用大写字母表示变量名，比如UPPER_CASE。

Ext编码规范与注意事项

1 Ext编码规范

编码规范主要包含类名称、变量和方法等的命名规范和代码规范。

1.1 命名规范

俗话说：无规矩不成方圆，良好的命名规范是一个系统、框架所必须具备的。

Ext源码都共用一个统一的命名规范，给它的源码带来了很强的可读性和易理解性。依据Ext的规范，根据定义的类别总结以下规范：

1.1.1 类名称

n 一般情况下，类名称由三部分组成，并采用驼峰命名法；第一部分为大写的命名空间，第二部分为小写的包名，第三部分为大写的类名。如：Ext.grid.Panel，Ext为命名空间，grid为源码所在包名称，Panel为包下的类名称。

当最小包时（类定义在最顶层文件夹里）为特殊情况，此时类名应该紧随命名空间，且两个部分都需大写。如：Ext.Component。

n 类名称仅可包含字母和数字，不要使用中划线和下划线；

如非技术术语中需用到数字，则不推荐使用数字。如MyComponent.util.Base64。

n 非Ext官方源码，不要使用Ext作为顶层的命名空间。

n 命名示例：

n

错误写法	正确写法
Foss.Module.MyDefinedClass	Foss. module. MyDefinedClass
Foss. module. myDefinedClass	Foss. module. MyDefinedClass
Foss. module.MYDefinedClass	Foss. module. MyDefinedClass

1.1.1 方法和变量

n 方法和变量的命名和类名称命名一样，遵循驼峰命名法；仅可包含字母和数字，且非技术术语中，不推荐使用数字。

n 命名示例：

错误写法	正确写法
var HTTPReader	var httpReader
var httpREADER	var httpReader
var the2Chid	var theSecondChid
GetMyData()	getMyData()
getJSONData()	getJsonData()
getXML()	getXml()

1.1.2 属性

n 非静态类的属性，命名规则和变量相同。

n 静态类的属性，属性全部使用大写字母。

示例

Ext.MessageBox.YES = ‘yes’;

Foss.module.MyDefinedClass.PI = ‘3.1415926’;

1.1.3 CSS样式

n CSS样式的名称可包含字母、数字和中划线，且字母全部采用小写，非技术术语，不推荐使用数字。如：.ext-ie6符合规范，ext-grid-2row不符合规范。

n CSS样式的名称结构通常为“前缀-组件-明细”，应遵循符合应用此CSS样式的对象所代表的具体内涵。如：.x-grid-cell，其中x为ext的CSS前缀，grid为此CSS样式应用的对象，cell为此对象的单元格，此样式很清楚表达了它的含义：应用在ext中grid上的单元格样式。

n 非Ext官方CSS样式，不要使用x作为样式前缀。

n 命名示例：

错误写法	正确写法
Foss-Form-Readonly	foss-form-readonly
foss-form-CheckBox-body	foss-form-checkbox-body
foss -row-focus	foss-mygrid-row-focus
x-form-radio-readonly（非Ext官方）	foss-form-radio-readonly

1.1.4 总结

n 类名称、变量、方法和属性的命名必须具备易理解、无歧义、方便阅读等特性。这就要求我们在命名的时候，除满足上述规范外，语义（名称的含义）也需要符合被命名对象具体代表的内涵。

如：getCurrentTime()定义为获取当前时间的方法，通过方法名，可以初步判断该方法的作用，一目了然；不推荐使用getTime()、getNowTime()、getCurrent()等语义模糊、错误的命名方式。

1.1 组件代码结构规范

杂乱无章的代码，总会让我们无阅览的欲望，代码具有良好规范，可以使代码具有良好的可阅读性和可维护性。根据Ext组件的代码，总结以下几点规范：

1.1.1 代码的基本结构为：

n 组件的属性

n 组件的初始化方法

n 组件的方法（有三种类型）

a) 与后台数据交互的方法

b) 供自己内部使用或外部调用的方法

c) 监听事件的处理方法

/** *  标准组件定义方式 */ Ext.define(Foss.example.MyComponent', {         /**          * 组件属性          */         extend: 'Ext.Component',         border: false,         frame: true,         /**          * 初始化话组件          */         initComponent: function(config) {                 var me = this;                 /**                  * 具体实现                  */                 me.callParent(arguments);         },         /**          * 与后台交互数据的方法          */         getData: function() {                 /**                  * 具体实现                  */         },         setData: function() {                 /**                  * 具体实现                  */         },         /**          * 供内部使用或外部调用的方法          */         getProperty: function() {                 /**                  * 具体实现                  */         },         getChild: function() {                 /**                  * 具体实现                  */         },         /**          * 监听事件的处理方法          */         onClick: function() {                 /**                  * 具体实现                  */         },         onBefordLoad: function() {                 /**                  * 具体实现                  */         } });

1.1.2 注意事项：

n initComponent方法的作用是初始化组件，如为组件初始化store、items等。此方法只适应于继承于Ext.Component的组件，它为构造方法中的一个初始化组件的方法，在构造函数中被调用。

n 对于组件（继承于Ext.Component），相对于constructor（构造方法），initComponent的任务就是为初始化组件，更具效率和针对性；两者之间为包含关系（constructor包含initComponent）。

1.2 注意事项1.2.1 模块及其包含子模块的菜单链接命名规范

n 某些模块中还需要细分成如干子模块，例如用户权限模块包含用户、角色、授权等子模块

n 由于模块对应的标签页的渲染对象ID（配置renderTo属性）的命名方式和标签页关闭后进行模块内内存回收的处理，导致模块和子模块的菜单链接（Action的URL）的命名方式必须符合一定的规则

1) 主框架js代码根据菜单树中从后台读取的菜单链接，动态生成标签页和页面渲染对象

2) 标签页关闭后，主框架js代码根据默认菜单链接（Action的URL）的命名规则找到所关闭的模块或者子模块进行内存回收的处理

命名示例

受理约车模块的菜单Action配置：#!acceptbookingcar/index.action

用户权限模块下的角色模块的菜单Action配置：#!authorization/roleIndex.action

用户权限模块下的用户模块的菜单Action配置：#!authorization/userIndex.action

1.2.2 模块中主面板和主工具栏的ID和渲染对象ID的命名规范

n 主面板中ID属性的命名规范必须遵循“前缀_包名-模块名-起始Action名称_后缀”

n 主面板中渲染对象ID的命名规范必须遵循“前缀_包名-模块名-起始Action名称-后缀”

n 主工具栏ID属性的命名规范必须遵循“前缀_包名-模块名-起始Action名称_后缀”

n 主工具栏渲染对象ID的命名规范必须遵循“前缀_包名-模块名-起始Action名称-后缀”：

命名示例

poc包下package模块下的主工具栏ID命名：T_poc-package-index_toolbar

poc包下package模块下的主工具栏渲染对象的ID：T_poc-package-index-body

poc包下package模块下的主面板ID命名：T_poc-package-index_content

poc包下package模块下的主面板渲染对象的ID：T_poc-package-index-body

1.2.3 模块中组件ID的命名方式

n 为快速通过ID辨识出组件，模块中组件的ID命名需遵循统一的规范。

n 模块中组件的ID命名规范为：类名称中点号（.）全部替换成下划线（_），后面加上“_ID”

命名示例

Foss.package.PackageGrid的id属性：Foss_package_PackageGrid_ID

Foss.package.SerialNumberWindow的id属性：Foss_package_SerialNumberWindow_ID

Foss.package.DetailPanel的id属性：Foss_package_DetailPanel_ID

2 Javascript编码规范

Javascript的设计不够严谨，存在缺陷。

遵守良好的Javascript编码规范，可以有效的避免它的缺陷。

2.1 大括号的位置

绝大多数的编程语言，都用大括号表示区块。起首大括号的位置，有许多不同的写法。

一种是起首的大括号另起一行：

block { ... }

另一种是起首大括号跟在关键字的后面：

block { ... }

一般来说，这两种写法都可以接受。

但是，Javascript要使用后一种，因为Javascript会自动添加句末的分号，导致一些难以察觉的错误。

return { key:value; };

代码的原意，是要返回一个对象，但实际上返回的是undefined，因为Javascript自动在return语句后面添加了分号。

为了避免这一类错误，需要写成下面这样：

return { key : value; };

规则1：表示区块起首的大括号，不要另起一行。

2.2 分号

分号表示语句的结束。大多数情况下，如果你省略了句尾的分号，Javascript会自动添加。

var a = 1

等同于

var a = 1;

因此，有人提倡省略句尾的分号。

但麻烦的是，如果下一行的第一个字元（token）是如下这五个字符之一，Javascript将不对上一行句尾添加分号。

圆括号	中括号	斜杠	加号	-减号
（	[	/	+	-

例如：

x = y 　　(function () { … 　　})();

等同于：

x = y(function (){…})();

规则2：不要省略句末的分号。

2.3 圆括号

规则3：调用函数的时候，函数名与左括号之间没有空格。

错误写法	正确写法
foo ();	foo();

规则4：函数名与参数序列之间，没有空格

错误写法	正确写法
function foo (arg) { … };	function foo(arg) { … };

2.4 相等和严格相等

Javascript有两个表示“相等”的运算符：“相等”（==）、“严格相等”（===）。

因为“相等”运算符会自动转换变量类型，造成很多意想不到的情况：

false == 'false' // false

false == '0' // true

规则5：不要使用"相等"（==）运算符，只使用"严格相等"（===）运算符。

2.5 变量声明

Javascript会自动将变量声明“提升”到代码块的头部。

if (!o) { var o = {…}; }

等同于：

var o; if (!o) { o = {…}; }

为了避免可能出现的问题，不如把变量声明都放在代码块的头部。

规则6：所有变量声明都放在函数的头部。

规则7：所有函数都在使用之前定义。

2.6 变量声明

Javascript最大的语法缺点，可能就是全局变量对于任何一个代码块，都是可读可写。这对代码的模块化和重复使用，非常不利。

规则8：避免使用全局变量，如果不得不使用，用大写字母表示变量名，比如UPPER_CASE。