精华内容
下载资源
问答
  • ARM位置无关代码设计规范

    千次阅读 2009-03-11 23:38:00
    /******************************...黄振华/*******************************************/位置无关代码(PIC)在嵌入式系统设计中具有很重要的作用,尤其是在裸机状态下bootloader程序以及进行内核初始化设计;利用PIC

     

    /*******************************************/
    参考:ARM的位置无关程序设计在bootloader中的应用.黄振华
    /*******************************************/
    位置无关代码(PIC)在嵌入式系统设计中具有很重要的作用,尤其是在裸机状态下bootloader程序以及进行内核初始化设计;利用PIC也可以构建高效的动态链接库。

    概念

    在设计bootloader的时候,必须在裸机状态下运行,这时bootloader映像文件的运行地址必须由程序员指定。通常情况下,将bootloader程序下载到ROM的0x0地址进行启动(比如固化到NorFlash中)。然而在很多的设计中,比如将bootloader固化在NAND中,在系统复位后S3C2440A中NAND控制器自动读取NAND中存储的前4K的代码到s3c2440a中称之为steppingstone的RAM中,steppingstone中的代码用进行一些非核心的硬件初始化,再将NAND中剩下的bootloader代码拷贝到RAM中运行。一般境况下两者的地址并不相同,程序在SDRAM中的地址重定位过程必须由程序员来完成。这样就有了位置无关代码的概念,指代码不在连接时制定的运行地址空间,也可以执行,它一段加载到任意地址空间都能执行的特殊代码。这样在steppingstone设计的代码要用位置无关设计。

    位置无关代码可以用于以下场合:

    1. 程序在运行期间动态加载到内存;
    2. 程序在不同场合与不同程序组合后加载到内存(共享的动态链接库);
    3. 在运行期间不同地址相互之间的映射(如bootloader)

    ARM位置无关程序设计要点

    ARM程序的位置无关可执行文件PIE(position independent executable)包括位置无关代码PIC(position independent code)和位置无关数据PID(position independent data)两部分。

    PID 主要针对可读写数据段(.data 段),其中保存已赋初值的全局变量。为实现其位置无关性,通常使用寄存器R9作为静态基址寄存器,使其指向该可读写段的首地址,并使用相对于基址寄存器的偏移量来对该段的变量进行寻址。这种方法常用于为可重入程序的多个实例产生多个独立的数据段。在程序设计中,一般不必考虑可读写段的位置无关性,这主要是因为可读写数据主要分配在SDRAM 中。

    PIC包括程序中的代码和只读数据(.text段),为了保证程序能在ROM和SDRAM空间中能真确的运行,必须采用位置无关代码程序设计。PIC 遵循只读段位置无关ROPI(Read-Only PositionIndependence)的ATPCS(ARM2Thumb Procedure Call Standard)的程序设计规范:

    1. 程序设计规范

    引用同一ROPI 段或相对位置固定的另一ROPI 段中的符号时,必须是基于PC 的符号引用,即使用相对于当前PC 的偏移量来实现跳转或进行常量访问。

    • 位置无关的程序跳转。

    在ARM 汇编程序中,使用相对跳转指令B/BL 实现程序跳转。指令中所跳转的目标地址用基于当前PC 的偏移量来表示,与链接时分配给地址标号的绝对地址值无关,因而代码可以在任何位置进行跳转,实现位置无关性。

    另外,还可使用ADR 或ADRL 伪指令将地址标号值读取到PC 中实现程序跳转。这是因为ADR或ADRL等伪指令会被编译器替换为对基于PC 的地址值进行操作,但这种方式所能读取的地址范围较小,并且会因地址值是否为字对齐而异。

    但在ARM 程序中,使用LDR 等指令直接将地址标号值读取到PC 中实现程序跳转不是位置无关的。

    例如:

    LDR   PC , = main
    上面的LDR 汇编伪指令编译后的结果为:
    LDR   PC , [ PC , OFFSET_ TO_L POOL ]
    ...
    LPOOL  DCD main

    可见, 虽然LDR 是把基于PC 的一个存储单元LPOOL 的内容加载到PC 中,但该存储单元中保存的却是链接时所决定的main 函数入口的绝对地址,所以main函数实际所在的段不是位置无关。

    • 位置无关常量访问

    在应用程序中,经常要读写相关寄存器以完成必要的硬件初始化。为增强程序的可读性,利用EQU 伪指令对一些常量进行赋值,但在访问过程中, 必须实现位置无关性。下面以 U-boot的
    SDRAM初始化介绍位置无关的常量访问方法。

    #define BWSCON 0x48000000

    /* BWSCON */
    #define DW8    (0x0)
    #define DW16    (0x1)
    #define DW32    (0x2)

    ...
    _TEXT_BASE:
     .word TEXT_BASE

    .globl lowlevel_init
    lowlevel_init:
     /* memory control configuration */
     /* make r0 relative the current location so that it */
     /* reads SMRDATA out of FLASH rather than memory ! */
     ldr     r0, =SMRDATA
     ldr r1, _TEXT_BASE
     sub r0, r0, r1
     ldr r1, =BWSCON /* Bus Width Status Controller */
     add     r2, r0, #13*4
    0:
     ldr     r3, [r0], #4
     str     r3, [r1], #4
     cmp     r2, r0
     bne     0b

     /* everything is fine now */
     mov pc, lr

     .ltorg
    /* the literal pools origin */

    ...

        .word ((REFEN<<23)+(TREFMD<<22)+(Trp<<20)+(Trc<<18)+(Tchr<<16)+REFCNT)
        .word 0x32
        .word 0x30
        .word 0x30

    汇编反汇编后
    lowlevel_init.o:     file format elf32-littlearm

    Disassembly of section .text:

    00000000 <_TEXT_BASE>:
       0: 00000000  andeq r0, r0, r0

    00000004 <lowlevel_init>:
       4: e59f0020  ldr r0, [pc, #32] ; 2c <.text+0x2c>
       8: e51f1010  ldr r1, [pc, #-16] ; 0 <_TEXT_BASE>
       c: e0400001  sub r0, r0, r1

    由此可以得出如下结论:

    使用LDR 伪指令将一个常量读取到非PC 的其他通用寄存器中可实现位置无关的常量访问;但将一个地址值读取到PC 中进行程序跳转时,跳转目标则是位置相关的。

    其他被ROPI 段中的代码引用的必须是绝对地址,或者是基于可读写位置无关( RWPI) 段的静态基址寄存器的可写数据。使用绝对地址只能引用被重定位到特定位置的代码段中的符号,通过在位置无关代码中引入绝对地址,可以让程序跳转到指定位置。例如,假设Bootloader 的阶段1将其自身代码拷贝到链接时所指定的SDRAM 地址空间后,当要跳转到阶段2 的C 程序入口时,可以使用指令“LDR PC, = main”跳转到程序在SDRAM 中的main 函数入口地址开始执行。这是因为程序在编译链接时给main 函数分派绝对地址,系统通过将main 函数的绝对地址直接赋给PC 实现程序跳转。如果使用相对跳转指令“B  main”,那么只会跳转到启动ROM 内部的main 函数入口。

     

    bootloadr、内核等程序刚开始执行的时候,他们所处的地址通常不等于运行地址。在程序的开头,先使用b、bl、mov等“位置无关”的指令将代码从flash等设备中复制到内存的“运行地址”处,然后再跳到“运行地址”去执行。

    U-Boot位置无关分析举例来自100ask,我做了以下修改

    -T board/smdk2410/U-Boot.lds -Ttext 0x33f80000
    ...
    SECTIONS
    {
      . = 0x00000000;
    ...
    }

    来自cpu/arm920t/start.S
    relocate:
      adr r0, _start
      ldr r1, _TEXT_BASE
      cmp r0, r1
      beq stack_setup

        当映像文件在nor flash中时,adr r0, _start 就想当于 sub r0, pc, #offset, 假设_start在映像文件的0位置出, nor flash地址从0开始,那么这时r0中的值就是0。

        当映像文件被加载到RAM后,adr r0, _start 还是相当于 sub r0, pc, #offset,但这里的pc值已经是基于RAM加载地址的了。所以结果r0中的值就是0x33f80000, 等于_TEXT_BASE。 判断这两个值是否相等,就可以确定映像是否已经加载到内存中了。 

    上面的代码的修改如下也行!

    T board/smdk2410/U-Boot.lds
    ...
    SECTIONS
    {
      . = 0x33f80000;
    ...
    }

    u-boot的连接地址是0x33f80000,意味着它“最后”将被复制到0x33f80000的内存中。
    但是“刚开始时”肯定不在内存中,而是在NOR FLASH中──而NOR FLASH的起始地址是0。
    为什么本应该在0x33f80000运行的指令,在0地址也可以运行?

    答:u-boot中第一个执行的文件是start.S,它都是使用b、bl等等指令写成的,它们是“位置无关的”,就是说它们可以在任何位置运行,而不是非要在“0x33f80000那段地址”运行。

    start.S完成什么功能呢?初始化、复制代码到SDRAM,然后跳到SDRAM去运行。

    上面的NorFlash你可以理解成S3C2440A中的steppingstone

    文件: ARM的位置无关程序设计在Bootloader中的应用.pdf
    大小: 502KB
    下载: 下载
    文件: 基于“Steppingstone”的Bootloader的设计与优化.pdf
    大小: 187KB
    下载: 下载

     

    展开全文
  • 良好的编程规范对于软件的开发与维护,至关重要!他不仅可以提高代码的可读性、可靠性、有效...对于一个团队协作的项目来说,人员的变动,一个良好的编程规范,有助于后续开发者和新手快速了解项目代码所要表现的含义。

    1文档信息

    条目

    内容

    项目编号

    通用

    项目名称

    通用

    标题

    JavaScript编程规范

    类别

    规范文档

    当前

    试用草稿

    摘要

     

    当前版本

    V1.0

    日期

    2015/11/9

    作者

    徐维坚(xuweijian)

    文档拥有者

    内部公开

    文件

    前端规范系列-JavaScript篇.docx


    2修改历史

    编号

    修订人

    修订内容简述

    修订

    日期

    修订前

    版本号

    修订后

    版本号

    V0001

    徐维坚

    编程规范文件编写,草稿试用版公布

    2015/11/10

     

    V1.0

     

     

     

     

     

     


    规范前言

    良好的编程规范对于软件的开发与维护,至关重要!他不仅可以提高代码的可读性、可靠性、有效性、健壮性,而且利于帮助开发人员开发和维护代码。对于一个团队协作的项目来说,人员的变动,一个良好的编程规范,有助于后续开发者和新手快速了解项目代码所要表现的含义。

    范围   

    本规范规定了使用JavaScript语言编程时排版、命名、声明、作用域、及一些特殊符号的规则和建议。  

    本规范适用于使用JavaScript语言编程的产品和项目。 

    术语和定义  

    规则:编程时强制必须遵守的原则。 

    建议:编程时必须加以考虑的原则。  

    格式:对此规范格式的的说明。 

    说明:对此规范或建议进行必要的解释。 

    实例/如:对此规范或建议从正、反两个方面给出的例子。

    1命名规范

    1.1基本规则

    规范的命名能使程序更易阅读,从而更易于理解。它们也可以提供一些标识功能方面的信息,有助于更好的理解代码和应用。

    1)      规则一:使用可以准确说明变量、函数、原型(prototype)的完整英文描述符。严禁使用汉语拼音、不相关单词及汉字进行命名,实例:firstName,listAllUsers或 CorporateCustomer等;

    2)      规则二:尽量少用缩写,但如果一定要使用或名称过长(不超过 25 个字母),当使用公共缩写和习惯缩写等,如实现(implement)可缩写成impl,经理(manager)可缩写成mgr等,严禁滥用缩写;

    3)      规则三:变量命名必须以小写字母开头,命名使用骆峰命名规则;

    4)      规则四:方法名必须使用动词或动词短语命名,实例:getIdcName()、export()等;

    5)      规则五:避免使用相似或者仅在大小写上有区别的名字,以免不严格区分大小写的系统视为同一名称;

    6)      规则六:避免命名中含有数字,但可以用2表示to,4表示for,另末尾使用数字表示同一系列的除外,如var$td_1 = $(‘.grid td’)[1];

    7)      规则七:类名、构造函数、公共对象实例等名称首字母大写。

    var MyCommon = {

        getSmallClassFromBigClass: function() {}

    }

     

    1.2相关建议

    以下为相关建议,非必要遵循,但需要考虑

    1)      建议一:变量如果设置为私有变量,函数为私有函数,则前面添加下划线进行标注;公有变量和函数不添加下划线

     实例一:

    var MyClass = function() {

    var _thisTotal = 0;

    var _doSomething = function() {};

    this.getThisTotal = function() {

        return _thisTotal;

    };

    };

    var myClassInstance = new MyClass();

    myClassInstance.total = myClassInstance. getThisTotal();

    实例二:

    function MyClass() {

    this._thisTotal = 0;

    this._doSomething = function() {};

    }

    MyClass.prototype.getThisTotal = function() {

        return this._thisTotal;

    };

    var myClassInstance = new MyClass();

    myClassInstance.total = myClassInstance.getThisTotal();

    2)      建议二:前面加"is" 的变量名应该为布尔值,同理 "has","can" 或者 "should"亦如此;

    3)      建议三:重复变量建议使用"i", "j", "k" (依次类推)等名称的变量;

    4)      建议四:全局变量、常量应该全部大写;

    5)      建议五:术语"initialize" 或者 "init" 作为变量名应为已经实例化(初始化)完成的类或者其他类型的变量;为函数,应为初始化操作。

    2代码组织规范

    基本原则:利于个人开发,便于相互交流。

    【说明】:因个人习惯和编辑器等可以设置而形成自己独特的风格,但必须前后一致,并符合本规范的基本规则、建议和格式。

    2.1缩排

    原则:

    (1)代码中以TAB(4个字符)缩进,在编辑器中请将TAB设置为相同的长度,否则在不同编辑器或设置下会导致TAB长度不等而影响整个程序代码的格式;

    (2)同一代码块中的代码对齐,这里所说的代码块,包括但不限于:function、if else语句、while、for等,即使用{}包围的代码。

    2.1注释

    原则:不吝惜代码注释,重要函数、变量必须添加注释;特殊函数、变量、常量必须添加注释。

    注释的格式,可参考如下所示:

    1)变量注释:

    // 初始化序列号

    var index = 0;

    var index = 0; // 初始化序列号

     

    2)函数注释,包括a.函数描述及其功能说明;b.参数描述应包括类型、参数名、参数描述;有返回值的需要对返回值进行相应描述:

    /**

    * 绑定事件

         * @param  {Object} $detailDom 当前变更详情页面主体DOM对象

         * @return null

         */

    function _bindEvent($detailDom) {

     

    /**

         * 查看专线详情

         * @param  {jQueryObject} $grid    列表DOM容器

         * @param  {String} selector 需要添加详情链接的选择器

         * @param  {Boolean} needSpecialId 是否需要指定其他特定id,默认不传,即false

         * @param  {String} specialIdName needSpecialId为true,此值必传,即指定id的属性名称

         * @return {Boolean} result 操作是否成功

         */

        viewDetail: function($grid, selector, needSpecialId, specialIdName) {

            var self = this;

        

     

    3)文件注释,应该包含文件描述、功能简介和作者,还可以加上创建时间:

    /**

     * 本js实现专线续费申请页面所有功能

    * @author xuweijian

     * @date 2015/10/12 15:25:33

     */

    $(function() {

     

    4)行注释与块注释:使用 //…的注释方法来注释需要表明的内容;使用/**和*/注释的方法来注释需要表明的内容。

    3 编码规范

    3.1 变量编码规范

    原则:在遵循命名规则之上,应遵守以下规则,

    (1)申明多个变量,变量之间使用逗号分隔;同时建议逗号与变量之间添加一个空格,避免过于拥挤,或是换行申明(此时可以对某个变量添加注释!),

    实例一:

    var name = ‘’, value = ‘’, title = ‘’;

    实例二:

    var name = ‘’,

    value = ‘’, // 注释

    title = ‘’;

     

    (2)变量申明时,应明确变量的类型,可以立即赋值,尽量避免变量的类型在使用过程中被转换;

    (3)尽量避免魔数(Magicnumbers),他们应该使用常量来代替;

    (4)声明变量必须加上 var 关键字,否则将成为全局变量(Document或者 Window),进而成为污染全局的变量;

    3.2 函数编码规范

    原则

    (1)       所有的函数在使用前进行声明,内函数的声明跟在var 语句的后面;

    (2)       不要在语句块(if…else等)内声明一个函数;

     

    其编码风格应该遵循这几点建议:

    1)  建议一:函数名与参数()之间不要留有空格;

    2)  建议二:参数列表之间使用逗号分隔,逗号与参数之间留有一个空格;

    3)  建议三:使用右侧简约模式,)与{之间留一个空格;

    4)  建议四:避免参数过多现象,一般不超5个,过多使用对象传入;

    5)  建议五:匿名函数不应该换行,如:$(‘#id’).bind(function(){…});中参数为匿名函数不应该换行处理,函数的主体遵循前面建议与原则;

     

    function outer(c,d)

    {

    var e = c * d;

    function inner(a, b)

    {

    return (e * a) + b;

    }

    return inner(0, 1);

    }

    // 简约模式

    function outer(c,d) {

    var e = c * d;

    function inner(a, b) {

    return (e * a) + b;

    }

    return inner(0, 1);

    }

     

     

           在函数体中,我们应遵循以下建议:

    1)建议一:避免提供多个出口;

    //不要使用这种方式,当处理程序段很长时将很难找到出口点

    if (condition) {

    return A;

    } else {

    return B;

    }

     

    //建议使用如下方式

    var result = null;

    if (condition) {

    result = A;

    } else {

    result = B;

    }

    return result;

     

    2)建议二:函数体中代码不应过长,一般不要超过100行;

    3.3表达式与语句

    原则表达式和语句应清晰、简洁,易于阅读和理解,避免使用晦涩难懂的语句。使用圆括号明确表达式执行优先级。

    3.3.1控制语句

    1)建议一:判断中如有常量,则应将常量置与判断式的右侧。如:

    if ( true == isAdmin())...

    if ( null == user)...

    2)建议二:boolean类型判断语句尽量明确条件比较值true/false

    //不建议使用

    if (isCond)...

    if (!isCond)...

     

    //尽量使用

    if (true == isCond)…

    if (false == isCond)…

    if (true != isCond)…

     

           编码风格应遵循以下建议:

    (1)       建议一:if…else if…else语句必须使用{}将每个判断条件后的执行语句括起来。

    (2)       建议二:if…else if…else与小括号、大括号之间应该空一格;

    (3)       建议三:条件中的变量与“==”、“===”之间应该空一格;

    (4)       建议四:类型确定的变量,在比较时,应使用严格相等符“===”,即”0” ===0比较值是false。

    3.3.2循环语句

    原则

    (1)       循环中必须有终止循环的条件或语句,避免死循环。

    (2)       当多层循环嵌套时,计数器变量注意不要有冲突。

    (3)       注意循环条件在执行循环过程中是否会发生变化,如果会则必须把循环条件的值在执行循环前获取而不要在每次循环去执行。

    (4)       考虑运行效率问题也应把循环条件值放在循环执行前获取。

     

    建议

    (1)       使用最基本的for循环,尽量避免使用for …in循环;

    (2)       for …in循环可用于用于object/map/hash 的遍历,对 Array 用 for-in 循环有时会出错,不建议使用;

    (3)       for循环中条件语句,不应该每次执行一个操作(如计算),应该在初始语句中实现;

    // 不建议每次查询length的值

    for (var i = 0; i < data.length; i++) {

     

    }

    // 建议在初始语句中赋值一个变量

    for (var i = 0, len = data.length; i < len; i++) {

     

    }

    3.3.3语句规范

    原则

    (1)    除了语句块最后一条语句可以没有分号“;”以外,每条语句必须以分号结束,以避免代码压缩后造成解析失败。

    (2)    当代码块中只有一条语句,也不应该省略大括号,如

    if (null == $tab) {

    return ; // 虽然只有一条语句,也不应该省略{}

    }

     

    3.3.4运算符规范

    原则

    (1)       赋值符号、比较符号两侧的变量应该在同一行,不要进行换行;

    (2)       字符串使用单引号(’)要优于双引号(”),尤其是在创建一个包含 HTML 代码的字符串时;

    3.4类、对象与原型链规范

    原则

    (1)       使用 Array 和 Object 字面量语法, 而不使用 Array 和 Object 构造器(newArray()),避免因传参不合适导致错误;

    (2)       其命名规范参考第1节中命名规范;

     

    编码风格,建议如下:

    1)比较长的标识符或者数值, 不要为了让代码好看些而手工对齐. 如:

    CORRECT_Object.prototype = {

    a: 0,

    b: 1,

    lengthyName: 2

    };

    不要这样做:

    WRONG_Object.prototype = {

    a          : 0,

    b          : 1,

    lengthyName: 2

    };

     

    2)属性名与属性值之间不应该拥挤,应该在冒号“:”与属性值之间空一格;

     

    3.5错误处理

    基本原则

    (1)       通常的法则是系统在正常状态并且用户正常操作下,不应产生任何异常。

    (2)       对可预见的错误不进行捕捉。

    (3)       对不可预见或者难以解决错误进行try{…}catch(e){..}捕捉处理。

    3.5.1可预见错误

    对可预见的错误不进行捕捉处理,而是在错误发生前通过条件判断避免发生,如:

    //若不对div1是否为null进行检查,则在其为null时会抛出缺少对象错误

    document.getElementById(“div1”).style.width = 100;

     

     

    //预先对对象进行检查

    var objDiv1 = document.getElementById(“div1”);

    if(objDiv1!=null){

           objDiv1.style.width = 100;

    }

    3.5.2不可预见错误

    对不可预见或者因浏览器、脚本解析器BUG造成的难以解决的错误需要进行捕捉处理,如:

    try{

           xmlhttp.open(“GET”,url,NOT_ASYNC);

    }catch(e){

           console.log(e.description);

    }

     

    【说明】:对捕捉到的错误一般情况必须给出反馈处理,例如console.log(),除非有必要提醒用户,否则不应该使用alert()。

    4 JavaScript其他规范

    以下规范,除了说明为建议、格式外,均为必须遵循的原则:

    (1)      eval是恶魔。eval 是JavaScript中最容易被滥用的方法,避免使用它。

    (2)      不要给setTimeout或者setInterval 传递字符串参数,应该使用函数参数。

    (3)      this仅在对象构造器, 方法, 闭包中使用。
    this 的语义很特别。 有时它引用一个全局对象(大多数情况下),调用者的作用域,DOM 树中的节点(添加事件处理函数时), 新创建的对象(使用一个构造器),或者其他对象(如果函数被call()或apply())。使用时很容易出错。

    【说明】:在内嵌函数想要使用外层函数的调用者,必须将外层调用者赋值给一个变量,通常是self。

    (4)      不要使用with(){}。

    (5)      千万不要修改内置对象, 如Object.prototype 和 Array.prototype 的原型;

    (6)      使用 join() 来创建字符串。

    通常是这样使用的,但这样在 IE 下非常慢:

    function listHtml(items) {

    var html = '<div class="foo">';

    for (var i = 0, len = items.length; i < len; ++i) {

    if (i > 0) {

    html += ', ';

    }

    html += itemHtml(items[i]);

    }

    html += '</div>';

    return html;

    }

    可以用下面的方式:

    function listHtml(items) {

    var html = [];

    for (var i = 0, len = items.length; i < len; ++i) {

    html[i] = itemHtml(items[i]);

    }

    return '<div class="foo">' + html.join(', ') + '</div>';

    }

     

     

    【说明】:即用数组作为字符串构造器, 然后通过join('') 转换成字符串。不过由于赋值操作快于数组的 push(), 所以尽量使用赋值操作.

     

     

     

     

     

     

     

     

     

     

     

     

     

    【参考文献】

    [1] JavaScript编程规范. http://wenku.baidu.com/view/f3a4cde95ef7ba0d4a733b38.html

    [2] Google JavaScript 编码规范指南. http://wenku.baidu.com/view/3a045b66b84ae45c3b358c18.html?re=view

    [3] js编码规范. http://wenku.baidu.com/view/ccd97ba20029bd64783e2c0e.html

    [4] javascript编程规范. http://wenku.baidu.com/view/b6e6a7d376eeaeaad1f3301e.html

     

     

     

    展开全文
  • Java代码注释规范

    千次阅读 2019-03-23 15:29:51
    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在日常开发中使用的代码注释规范,供...

     

    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在日常开发中使用的代码注释规范,供大家参考下。

    1. 注释形式统一

    在整个应用程序中,使用具有一致的标点和结构的样式来构造注释。如果在其它项目中发现它们的注释规范与这份文档不同,按照这份规范写代码,不要试图在既成的规范系统中引入新的规范。

     

    1. 注释内容准确简洁

    内容要简单、明了、含义准确,防止注释的多义性,错误的注释不但无益反而有害。

    注释条件

    1、基本注释

    (a)    类(接口)的注释

    (b)    构造函数的注释

    (c)     方法的注释

    (d)    全局变量的注释

    (e)    字段/属性的注释

     

     备注:简单的代码做简单注释,注释内容不大于10个字即可,另外,持久化对象或VO对象的gettersetter方法不需加注释。具体的注释格式请参考下面举例。

    2、特殊必加注释

    (a)    典型算法必须有注释。

    (b)    在代码不明晰处必须有注释。

    (c)     在代码修改处加上修改标识的注释。

    (d)    在循环和逻辑分支组成的代码中加注释。

    (e)    为他人提供的接口必须加详细注释。

     

     备注:此类注释格式暂无举例。具体的注释格式自行定义,要求注释内容准确简洁。

    注释格式

    1、单行(single-line)注释:“//……”

    2、块(block)注释:“/*……*/”

    3、文档注释:“/**……*/”

    4、javadoc 注释标签语法

    @author   对类的说明 标明开发该类模块的作者

    @version   对类的说明 标明该类模块的版本

    @see     对类、属性、方法的说明 参考转向,也就是相关主题

    @param    对方法的说明 对方法中某参数的说明

    @return   对方法的说明 对方法返回值的说明

    @exception  对方法的说明 对方法可能抛出的异常进行说明

    参考举例

    1. 类(接口)注释

    例如:

    /**

    * 类的描述

    * @author Administrator

    * @Time 2016-11-14:49:01

    *

    */

    public classTest extends Button {

      ……

    }

     

     

    2.   构造方法注释

    例如:

    public class Test extends Button {

      /**

       * 构造方法 的描述

       * @param name

       *       按钮的上显示的文字

       */

      public Test(String name){

         ……

      }

    }

     

     

    3.   方法注释

    例如

    public class Test extends Button {

      /**

       * 为按钮添加颜色

       *@param color

             按钮的颜色

    *@return

    *@exception  (方法有异常的话加)

    * @author Administrator

    * @Time2012-11-20 15:02:29

       */

      public voidaddColor(String color){

         ……

      }

    }

     

     

    4.   全局变量注释

    例如:

    public final class String

       implements Java.io.Serializable, Comparable<String>,CharSequence

    {

       /** The value is used for characterstorage. */

       private final char value[];

       /** The offset is the first index of thestorage that is used. */

       private final int offset;

       /** The count is the number of charactersin the String. */

       private final int count;

       /** Cache the hash code for the string */

    private int hash; // Default to 0

    ……

    }

     

     

    5.   字段/属性注释

    例如:

    public class EmailBody implements Serializable{

       private String id;

       private String senderName;//发送人姓名

       private String title;//不能超过120个中文字符

       private String content;//邮件正文

       private String attach;//附件,如果有的话

       private String totalCount;//总发送人数

       private String successCount;//成功发送的人数

       private Integer isDelete;//0不删除 1删除

       private Date createTime;//目前不支持定时 所以创建后即刻发送

       privateSet<EmailList> EmailList;

    ……

    }

     

    其实规范是自己订的,只要团队中大家都统一遵守,统一规范,就会取得好的效果,希望对平时不加注释的朋友有点帮助。

     

     

    展开全文
  • 代码仓库规范

    千次阅读 2018-12-24 12:33:28
    代码仓库规范 目录 背景 目标 代码仓库规范 仓库创建 权限管理 仓库初始化 .gitignore README.md 分支管理 Tag管理 代码仓库列表 参考链接   背景 代码仓库不规范往往会带来各种问题,影响代码质量...

     代码仓库规范

    目录

    背景

    目标

    代码仓库规范

    仓库创建

    权限管理

    仓库初始化

    .gitignore

    README.md

    分支管理

    Tag管理

    代码仓库列表

    参考链接
     

    背景

    代码仓库不规范往往会带来各种问题,影响代码质量及开发效率,如:

    1. 项目开发阶段,混乱的分支可能引起多人合作开发过程中的代码冲突

    2. 项目运维阶段,新功能或bug修复导致线上故障难以回滚

    3. 项目代码缺乏review,代码质量存在隐患

    4. 项目组中添加新同学,代码上手开发时间成本较高

    针对以上问题,制定代码仓库规范,通过流程化方式降低问题出现的可能性。

    目标

    除解决背景中提到的问题外,代码仓库规范旨在达成以下目标:

    1. 业务可持续:避免项目迭代到后期线上、开发等分支错乱,确保系统代码长期可维护,业务变化可追溯

    2. 知识传承:项目新同学可根据代码重复流程,降低上手成本,促进知识不断积累、传递

    3. 远程仓库整洁:只提交项目开发/测试/运行相关的文件,IDE配置文件、编译文件等不可上传污染远程仓库

    代码仓库规范

    仓库创建

    项目主R负责申请创建项目代码仓库,代码仓库的创建应遵循以下原则:

    1. 按照不同的项目创建相应的代码仓库,避免不相关项目的代码放到一个库

    2. 避免按工程创建代码库,易导致代码仓库过多的问题。合理做法是按业务或按功能将同类工程放入一个代码仓库中

    权限管理

    合理的权限管理可以避免项目主分支合入未review代码,权限管理应遵循以下原则:

    1. 项目成员拥有非主分支Write权限,组内非项目成员拥有Read权限

    2. 项目主R保留主分支Write权限,同时按需为相应同学开放Write权限

    3. Leader保留Admin权限

    仓库初始化

    .gitignore

    原则上除了源代码、配置文件、单元测试代码、数据库初始化SQL,其他文件都应该加入到 .gitignore 以避免上传至远程仓库。

    通用 .gitignore 文件模板如下,各项目可根据需要补充:

    代码块

    Plain Text

    .idea/
    .DS_Store
    *.iml
    target/
    *.log
    *.class
    .settings/
    .project
    *.jar
    *.war
    *.nar
    *.ear
    *.zip
    *.tar.gz
    *.rar

    README.md

    README文件的目的是帮助代码仓库的浏览者快速了解项目相关信息,在README文件中需要包含以下信息:

    1. 简要说明此代码库解决的问题

    2. 项目结构简介,以模块粒度说明每个模块的作用、运行环境、线上链接等

    3. 项目文档外链,如需求文档、设计文档等

    4. 其他注意事项,如项目特殊依赖等

    5. 问题及需求反馈

    README示例:

    分支管理

    良好的分支管理可以提高项目主分支代码质量,较为完整的分支示例及对应分支说明如下:

    分支名称

    说明

    作用

    注意事项

    由何分支检出(checkout)

    向何分支合入(merge)

    何时删除

    master

    主分支/线上分支

    上线前该分支打Tag

    保留Write权限,由项目主R进行合入

    N/A

     

    N/A

    develop

    公共开发分支

    供feature-*分支检出、合入,作为项目开发过程中的核心分支

    保留Write权限,项目开发成员不可直接在该分支提交代码,需要以PR方式合入

    master

    release-*

    N/A

    feautre-*

    个人开发分支/新功能分支

    项目开发成员各自独立持有使用

    开发人员间不可混用,避免开发过程中发生冲突

    develop

    develop

    完成合入操作后删除

    release-*

    预上线分支

    feature-*分支汇总至develop分支后进行预上线测试使用

    除修复测试出的bug外不做其他修改及提交

    develop

    master

    develop

    完成合入操作后删除

    hotfix-*

    线上bug修复分支

    临时性紧急修复线上bug

     

    master

    master

    develop

    完成合入操作后删除

    由于组内项目在进行项目拆分后(预计国庆节后开始项目拆分)同一代码仓库只会由2~3人同时维护,采用上述分支模板会降低开发效率且不会取得太高的收益,因此引入分支权限,使用较为简洁的分支进行开发及管理,只保留master、feature-*分支,遵循以下原则:

    1. 仓库必须有一个主分支(master),主分支只有部分同学有Write权限

    2. 上线作业/工程必须采用主分支上的代码

    3. 开发新功能(feature)、修复bug、测试,统一使用feature-*分支(简洁分支管理不存在develop分支,feature-*分支从master分支检出)

    4. feature-*分支向主分支合入需要以PR形式进行,并配合Code review,完成后由具有Write权限的同学合并至主分支

    5. 定期删除已合并至主分支的feature-*分支,避免仓库分支过多难以管理

    Tag管理

    Tag可以理解成不可更新的特殊分支,也可以理解为某次commit指定的易于理解的别名,方便项目发布过程中的版本管理及线上问题回滚。Tag管理遵循以下原则:

    1. Tag需要在上线前创建,上线所用的Tag需要在主分支上创建

    2. 项目上线需要以Tag为基准(例外:离线托管平台上的Spark等作业需要指定分支发布),保证线上发布版本能够找到对应Tag

    3. Tag一般不做删除

    Tag示例:

     参考链接

     

     

    展开全文
  • 代码规范

    千次阅读 2016-10-09 10:21:45
    下面总结一下OC编程中的一些代码规范(苹果官方推荐的)。以OC为示例,但不局限于OC,也可以被当作别的编程语言的开发规范约定(仅需要把OC特有的东西按照你所使用的语言的惯例即可)  参考资料:苹果代码规范 对建议...
  • 代码编写规范

    万次阅读 多人点赞 2019-04-23 22:48:44
    排版格式2.1 类及其排版格式2.2 函数的声明与定义2.3 空行2.4 代码行2.5 代码行内的空格2.6 对齐2.7 长行拆分2.8 修饰符的位置2.9 代码段中的预处理格式2.10 被注释的代码2.11 注释3.命名规则4.表达式和基本语句4.1 ...
  • verilog 代码编写 ,FPGA设计规范

    千次阅读 2018-05-14 11:01:22
    逻辑设计也是这样:如果不按规范做的话,过一个月后调试时发现有错,回头再看自己写的代码,估计很多信号功能都忘了,更不要说检错了;如果一个项目做了一半一个人走了,接班的估计得从头开始设计;如果需要在原来的...
  • Java代码规范编程

    千次阅读 2013-10-30 17:18:59
    1、代码注释规范 【情景一】在接口类添加方法注释  对接口的方法加以说明是相当有必要的,方法的作用、参数的名称、以及返回类型都需要做出明确的定义。如果接口添加了完整的注释,在它的实现类基本上都不需要注释...
  • Python 代码规范

    千次阅读 多人点赞 2017-06-13 00:44:49
    前言Python 学习之旅,先来看看 Python 的代码规范,让自己先有个意识,而且在往后的学习中慢慢养成习惯目录一、简明概述1、编码 如无特殊情况, 文件一律使用 UTF-8 编码 如无特殊情况, 文件头部必须加入#-*-coding:...
  • CSS代码编码规范

    千次阅读 2016-03-16 10:51:56
     CSS代码编码规范 类似HTML,代码编写规范帮助程序员很好的规整和管理代码。这里介绍一些CSS编码的相关规范。 有效组织注释 CSS文件可以非常复杂,或许包含了几百行。这些巨大的文件可能会导致我们书写的样式...
  • 谷歌开源内部代码评审规范

    千次阅读 2019-10-08 15:33:58
    近日,谷歌开源了其内部一直在使用的代码评审规范,InfoQ 对其进行了翻译和整理,分享给广大开发者,看看谷歌工程师是如何评审代码的。 代码评审标准 代码评审的主要目的是确保代码库的整体质量随时间...
  • 代码规范

    千次阅读 多人点赞 2019-05-09 20:10:58
    原文链接:https://www.cnblogs.com/huipengkankan/archive/2011/07/28/2120416.html伪代码(Pseudocode)是一种算法描述语言。...因此,伪代码必须结构清晰、代码简单、可读性好,并且类似自然语...
  • HTML代码编码规范

    千次阅读 2016-03-16 11:03:01
    为了保证项目代码的质量,书写HTML和CSS相关代码的时候,需要遵循一定的规则和逻辑,虽然HTML相关代码没有太复杂的逻辑,并且记得一定要验证代码正确性,下面是一些相关的编码规范 书写符合兼容性的代码 为了保证...
  • C语言 程序代码编写规范

    千次阅读 2016-04-28 15:47:32
    前言 一个好的程序编写规范是编写高质量程序的保证...l 对于具有一定工程项目开发经验的程序员,建议学习C语言程序代码编写规范—高级版。 目录 1 代码书写规范 2 注释书写规范 3 命名规范 4 其它一些小技
  • Python代码规范和命名规范

    万次阅读 多人点赞 2017-10-26 14:40:47
    Python代码规范和命名规范 前言 Python 学习之旅,先来看看 Python 的代码规范,让自己先有个意识,而且在往后的学习中慢慢养成习惯 目录 一、简明概述 1、编码 如无特殊情况, 文件一律使用 UTF-
  • C#代码规范

    千次阅读 2015-11-12 10:24:41
    C#命名规范C#代码规范 1.注释写在上面,充分利用C#的提示 2.短路写法,把大量的前提预先处理,可以让代码实现逻辑更清晰,并能有效的所见代码嵌套深度 3.要常用自带的Action Func Predicate委托类型 不要引入...
  • 阿里巴巴代码规范

    千次阅读 2017-09-29 17:04:28
    规范均出自阿里巴巴代码规范以及本人日常过程中的积累。由于篇幅有限,本文不予列出阿里巴巴代码规范的所有,仅列出本人觉得对日常使用过程中帮助较大且又是大家容易忽略的问题。 阿里巴巴代码规范:...
  • JAVA代码注释规范

    千次阅读 2017-04-25 01:59:27
    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下在开发中使用的代码注释规范,供大家参考下...
  • 代码规范,同事两行泪?

    千次阅读 多人点赞 2021-02-26 00:51:21
    最近参加了一个比赛,然后看到队友编程的代码,我觉得真的是觉得注释和命名规范的重要性了,因为几乎每个字符都要咨询他,用老师的话来说,这就是命名不规范的后续反应。所以此时的我意识到写一篇关于注...
  • java代码注释规范

    万次阅读 多人点赞 2012-11-20 20:20:13
    代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在诉求网二期开发中使用的代码注释规范...
  • 嵌入式代码编写规范

    千次阅读 2017-04-09 17:11:34
    **嵌入式代码编写规范** ————- 该文章是自己总结出来的编码风格,用于规范自己的代码,增强可读性,非标准规范。强制自己形成良好的编码风格,有利于开发大规模程序而不显得杂乱。 参考STM32固件库编码风格和...
  • 前端代码风格规范

    千次阅读 2018-07-25 09:54:45
    规范目的:为了提高工作效率,便于后台人员添加功能及前端后期优化维护,输出高质量的文档,在网站建设中,使结构更加清晰,代码简明有序,有一个更好的前端架构。 规范基本准则:符合web标准,使用具有语义的标签...
  • 前端代码规范手册

    千次阅读 2018-08-15 15:43:15
    前端代码规范手册       Web Coding Guidelines     前言 本手册的愿景是码出高效,码出质量。现代软件架构都需要协同开发完成,高效 协作即降低协同成本,提升沟通效率,所谓无规矩不成方圆,无规范不...
  • Verilog HDL学习笔记——设计规范
  • 代码规范】常见编码规范

    万次阅读 2018-06-22 16:40:54
    1.明确方法功能,精确(而不是近似)地实现方法设计。如果一个功能将在多处实现,即使只有两行代码,也应该编写方法实现。说明:虽然为仅用一两行就可完成的功能去编方法好象没有必要,但用方法可使功能明确化,增加...
  • java代码规范

    千次阅读 2019-04-22 15:19:10
    大的角度来说,代码规范是一种本行业约定俗称、默认遵从的普遍规则,但是除此之外,根据各公司不同甚至各人习惯不同,又会在原有规则上进行一些变通,以下规范两者兼有,大家可以择优而取。 1. 标识符命名规范 1.1 ...
  • C++代码编写规范

    千次阅读 2016-11-30 10:35:21
    C++代码编写规范 1 头文件 1.1 使用头文件保护 使用#define进行头文件保护,而不使用微软的#pragma once。 为了保证唯一性,头文件保护的命名需要基于项目代码路径,比如Project\Src\Area\File.h 则文件的保护...
  • Lua代码编写规范

    千次阅读 2015-07-23 22:04:26
    Lua代码编写规范 开发中,大量使用lua,暂时根据当前状况,总结相对而言较好的规范,在多人协作中可以更好的开发、交流。 介绍 该文档旨在为使用lua编写应用程序建立编码指南。 制订编码规范的目的: 统一编码...
  • 代码书写规范

    万次阅读 2019-03-20 16:48:37
    代码(Pseudocode)是一种算法描述语言。使用伪代码的目的是为了使被描述的算法可以容易地以任何一种编程语言(Pascal,C,Java,etc)实现。因此,伪代码必须结构清晰、代码简单、可读性好,并且类似自然语言。 ...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 492,880
精华内容 197,152
关键字:

代码设计规范