代码规范

Posted jason-beijing

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了代码规范相关的知识,希望对你有一定的参考价值。

版本管理
 
 
时间
版本号
内容
整理
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文件的存放路径】

以上是关于代码规范的主要内容,如果未能解决你的问题,请参考以下文章

青青草原--团队作业6:代码规范

是否需要有代码规范

Beta冲刺代码规范

作业三: 代码规范代码复审PSP

作业三: 代码规范代码复审PSP

代码规范代码复审PSP