代码规范

Posted 2022-07-29 jason-beijing

• 书写原则
• 命名规范
• 包
• 类
• 函数
• 类级变量
• 函数内局部变量
• 表示事件的类型的常量
• 事件响应函数
• 组件 
• 缩略单词
• 缩略词组
• 词组的连接
• 子类
• 常量
• 循环变量
• 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文件的存放路径】