代码注释规范说明
Comments criterion of the Code 在多个PROJIECT共同开发的前提下,为了减少修改升级CODE过程中出现失误和方便SI人员对代码的维护,加强部门整体代码注释规范,建议通过在每一次代码修改过程中添加代码标志符进行注释,这样可以使软件工程师在升级代码的过程中减少错误率,同时可以保持对以前版本代码的修改思路清晰,能在最短时间里复查代码中的错误。标准C+/C的文件结构:/ Copyright (c) Microsoft Corporation. All rights reserved./ Use of this source code is subject to the terms of the Microsoft end-user/ license agreement (EULA) under which you licensed this SOFTWARE PRODUCT./ If you did not accept the terms of the EULA, you are not authorized to use/ this source code. For a copy of the EULA, please see the LICENSE.RTF on your/ install media./* Port Copyright (c) Hisys Corporation. All rights reserved.* file batt_pdd.c* Abstract* This file contains battery driver PDD implementation.* Change Log* 2006.2.21 Shi Yuehua Initial Version*/代码注释规范如下:/*COMMENTS-HISTORY*/*NAME | SIGN | PROJECT | SUMMARY *-*Johson.Li M060806_A HXS006 Use the two methods to measure the battery voltage.*Johson.Li M060812_A HXS010 Change the init array value from 4 to 8.*Johson.Li M060812_B COMMON Change the USB CHANGING conditions.* .* .*/代码注释标题声明包含四部分: 1.作者名称 2.标记符 3.项目名称 4.摘要1.NAME:修改该部分CODE的软件人员名称(英文名称&中文名称拼音缩写),第一个字母大写。2SIGN:该标记符应在所有本次修改代码前面声明,主要是为了方便搜索,当我们想查找本次为了实现某个功能所做的代码修改时,可以搜索此标记符,即可找到全部修改过的相关代码段。 标记符:M060806_AM: 英文<Modify>缩写 A:代表当天添加或者修改的第一项功能。如果当日继续做其他有别与本次功能差异的修改,可以采用M060806_B的方法,依次类推(A、B、C、D、E、F) .3PROJECT:主要描述当前代码的修改所针对的项目,由于以后的多个项目可能用一套代码通过宏来定义,所以如果当前代码的修改是针对两个或两个以上的项目,我们这里使用COMMON加以区分。4.SUMMARY:主要简述此次代码修改的目的或者解决某个BUG的方法。*Sample-1:/M060806_A start/*Do Battery Voltage Measure*/static BOOL g_batteryADC = FALSE;static DWORD dwCyc = 0;static DWORD dwCount = 0;/M060806_A end<Sample-2>:/M060812_B start-Change the USB CHANGING conditions/*if(gpioGetValue(g_pGPIOregs,80) = 0) / nCHG assertif(dwVolt < g_pdd.voltMax + 10) g_sps.BatteryFlag = BATTERY_FLAG_CHARGING;else g_sps.BatteryFlag = BATTERY_FLAG_HIGH;goto done;dwPercent < 100*/if(dwVolt < g_pdd.voltMax) && (gpioGetValue(g_pGPIOregs, 1) = 0)/Here we do not to judge the CHG_nCHG PIN.g_sps.BatteryFlag = BATTERY_FLAG_CHARGING;goto done;/M060812_B end如果在代码修改过程中由于需要定义新的变量,可以参照Sample-1的方法。在修改代码段<Sample-2>的过程中,我们最好在修改代码段暂时保留注释掉的源代码,这样方便我们以后如果出现问题时对修改代码和旧代码的对比检查。注释掉的源代码,在通过正式版本的测试验证无误后,相关人员可以删除针对这个问题的所有标志符和相关代码。具体操作可以参照Sample Code<Bat_pdd.c>! 希望大家有更好的建议或者方法,提出来大家共同讨论制定这项代码规范!谢谢!Author:lizhuangzhi