代码规范

• 书写原则
• 命名规范
• 包
• 类
• 函数
• 类级变量
• 函数内局部变量
• 表示事件的类型的常量
• 事件响应函数
• 组件 
• 缩略单词
• 缩略词组
• 词组的链接
• 子类
• 常量
• 循环变量
• getter/setter 变量
• 偏向属性设置类型的函数名
• 布尔性变量
• 代码级书写规范
• 类型声明
• 初始化
• +与—操做符
• import 类
• if
• switch
• 逗号
• 数组里的元素
• 大括号
• 工程级书写规范
• 注释
• 外部模块的使用
• 日志记录
• 警告
• 代码行数
• 代码修改
• 版本号
• 附录:生成ASDoc的方法:

版本管理

 

 

时间	版本号	内容	整理
2013年10月	V1.0	初建	xiaojianjun

 

1. 书写原则

    

   要表达的意思完整准确，

   易于理解，易于记忆，易于他人扩展维护，

   简洁，不用拼音，使用英语，

   一般用骆驼命名法和下划线间隔法，

   傻瓜写的代码只有计算机看得懂，好工程师写的代码人看的懂，

   达成规则的约定后，即便有疑义，也要遵照。

    

2. 命名规范

1. 包

   第一个字段是com. 第二个字段是公司名，每三个字段应该是产品线的名字，咱们以全小写的方式来给包命名，最好使用名词或者动名词，而不要使用动词，副词，或者形容词：　好比com.vox.afenti.model.wordcorrection
1. 若是一个包名实包含了若干实现了类似功能的类，那就用一个名词的复数形式来作包名，好比 charts, collections, containers 。
2. 若是一个包包含了实现了一类功能的类，那就用动名词来作包名，好比 binding, logging, messaging, printing 。
3. 若是一个包里面的类都支持同一个组件，好比 FooBar，那就取名叫 foobarclasses
    

2. 类

   以大写字母开头，名词［+模式] 的形式构成，“模式”是指MVC中的模式。好比ControlView , ButtonFactory

3. 函数

   动词［＋名词］，以小写字母开头。推荐函数所带的形参以 $ 符号开头，且用有意义的词汇代码通性词汇，好比用 $price 代码 $value 。 

4. 类级变量

   私有变量定义以”_”开头，静态变量一般以大写字母开始。

5. 函数内局部变量

   以小写字母开头，不要与类级变量名称重名。

6. 表示事件的类型的常量

   为了和类中的其余常量区分，要以Evt_开头 

7. 事件响应函数

   on发出事件的对象_事件名Handler。好比 onStopBtn_clickHandler

8. 组件 

   名称定义要有package，最好加上后缀来讲明本组件的类型，好比 com.iqiyi.player.components.ConfirmBtn。

9. 缩略单词

   在保证别人看得懂的状况下，能够用缩略词，有一些公认的缩略词：acc 代替 accessibility, 好比： ButtonAccImplauto 代替 automatic, 好比： autoLayoutauto 代替 automatic, 好比： autoLayouteval 代替 evaluate, 好比： EvalBindingResponderimpl 代替 implementation, 好比： ButtonAccImplinfo 代替 information, 好比： GridRowInfonum 代替 number of, 好比： numChildrenmin 代替 minimum, 好比： minWidthmax 代替 maximum, 好比： maxHeightnav 代替 navigation, 好比： NavBarregexp 代替 regular expression, 好比： RegExpValidator

10. 缩略词组

    缩略词组一般用所有大写或者所有小写，好比 SWF 或者 swf ，可是 Swf 是不容许的，所有小写的缩略词组一般只在只包含缩略词组的变量，或者必须以小写开头的变量里面，好比 uid，imeMode，其他时候就应该用大写。

     

11. 词组的链接

    驼峰式( 好比LayoutManager ) 与下划线连结式 ( 好比 object_proxy )一般用驼峰式，有不少单词的时候使用驼峰式，会难于看懂，这时可用下划线连结式，但尽可能少用。

12. 子类

    通常以父类的命名来结尾，好比： Event 的子类 FooBarEvent。

     

13. 常量

    常量命名所有采用大写字母，而且用下划线的方式链接多个单词，力求语义表达完整，不要嫌名字长。变量名必须与值的单词一致，只是大小写不同而已 ( 笔者认为彻底同样也能够 ) 。好比： public static const FOO_BAR:String = “fooBar”;

     

14. 循环变量

    通常在for循环的第一层里面使用i作临时变量，用j作第二层作临时变量， 但笔者我的认为用有意义的词汇来表示更好。好比 row, column 。

15. getter/setter 变量

    若是一个getter/setter方法是foo，那相对应的存储变量（私有变量）应该为 _foo。

16. 偏向属性设置类型的函数名

    好比 getFooBar() 有时候可能实现了太多功能，那尽可能采用 calculateFooBar()，findFooBar()，determineFooBar( ) 之类的命名。

17. 布尔性变量

    这类变量要注意很容易理解反。建议这类变量的意义都要是确定正面的。

     

3. 代码级书写规范

1. 类型声明

   类型声明类型范围越小越好。好比，循环脚标必须采用 int 型，而非Number型，
1. 采用具体类型，而不要用Object或者 * 类型。
2. mouseDownHandler函数的参数要用MouseEvent，而不要用Event
3. 就算是一个非负整数，也尽可能声明为整数。
4. uint只在RGB的颜色值，位运算与其余非数值类型里面用到
5. 只在一个值可能为undefined的时候用，若是一个值在未出生以前为null，那就用Object类型，而不要用*

2. 初始化

1. 初始化数组的时候尽可能使用 [ ] ，而非 new Array ( )
2. 初始化最基础对象时，使用{ } 代替new Object( )

3. +与—操做符

   尽可能选择后置的 + , – -

    

4. import 类

   最好写完整导入的类的全饰路径，不用使用.*

5. if

1. 若是一个if后面只跟了一个语句，那就不要用{ }的语句块了，直接用单句就能够了，但请不要换行。
2. 把最有可能出现的条件写在最前面

6. switch

   全部case块都要以break结束

    

7. 逗号

   逗号后要一位空格.

    

8. 数组里的元素

1. 数组的左边括号后，右括号前都要用空格符，而且每一个逗号后面都应该有空格符
2. 若是元素不少，请用多行来格式化。
    

9. 大括号

   要单独占一行，要用 tab 上下对齐缩进

    

    

4. 工程级书写规范

1. 注释

1. 原则: 准确，为方便他人，只要有其它人有可能看不懂的地方，就有必要加注释.4.1.2 对于接口（特别是独立模块的对外统一接口）必须添加注释，说明接口的意义与使用过程当中的注意事项.
2. 类模块须要增长简要的功能说明，类模块的说明要在构造函数以前。

2. 外部模块的使用

   外部模块为第三方模块，该模块由非本组成员（或本公司）完成。应该将该模块编绎成库（ SWC 或 SWF ）来使用，模块最后生成应该为：{name}-{version}.{extension}，好比，JSON库的命名能够为：as3corelib-0.92.swc。在开发应用的每一版本中，应该明确对第三方库的版本依赖。如需修改第三方模块的，能够对其进行扩展以后，造成模块与应用关联。

    

3. 日志记录

   日志记录按照log4j标准执行（as3代码已经实现）。在程序中定义日志等级的时候，要慎重对待，特别是release阶段的日志。Debug信息的输出分为两种，一种是经过trace输出，一般是用于调试阶段，另外一种是经过第三方工具（如Arthropod），用于测试阶段的bug排查，这部分信息能够有比较大的冗余。

   在flash项目中，为了明确日志层级，做出如下约定：
1. DEBUG：用于debug阶段，该级别的信息调试阶段，帮助开发人员进行调试工做。
   （如下为release阶段）
2. INFO： 一般写在用户的日志中，当用户投诉，将该信息上传，该信息要求精练且严谨。
3. WARN：当程序发生错误，但不影响正常流程，对用户影响不大。
4. ERROR: 程序发生错误，不影响正常流程，但已经严重影响用户使用。
5. FATAL：程序发生严重错误，影响正常逻辑。
    

4. 警告

   警告的缘由一般是由错误或定义不明确（也就是说写代码的人可能并不明确其中的意思），所以，为提升代码质量，必须杜绝一切编绎警告。

    

5. 代码行数

   代码行数绝大多数状况下，不计注释，代码行数不该超过300行，底线是500行。对于须要超过500行的模块，通常状况下，应该是不合理的，应该考虑对该模块进行细化。

    

6. 代码修改

   尽量不要删除原有代码，采用注释的办法，注释时要标明修改人，修改时间，以及为了解决什么问题而修改。当达到一个比较稳定版本以后，并在一段时间以后，经过讨论，肯定之前的代码无用的状况下，能够删除相关注释代码。

    

7. 版本号

   在目前只有一个版本号的状况下，版本号由产品部门与技术部门共同维护。在版本号定义上统一为：以小数点分割的三个数字为版本号（x1.x2.x3）各版本号的意义：

   X1 主版本号，通常用于对系统重构时更改。

   X2 次版本号，通常用于有重大更新时更改。

   X3 build版本号，通常用于bug修复和小的改进。当主版本号发生变化时，另两个版本号要归零。

   提测时，应该在版本号后增长一个，即：x1.x2.x3.x4。其中x4表示提测版本号。正式上线时，删除x4。

    

5. 附录:生成ASDoc的方法:

1. 打开cmd命令行窗口
2. 执行命令:asdoc -source-path 【 src文件夹的路径(包括src) 】-library-path 【全部库文件的路径】-doc-sources 【生成的ASDoc文件的存放路径】