代码注释规范

最新推荐文章于 2024-04-24 08:20:25 发布
最新推荐文章于 2024-04-24 08:20:25 发布
阅读量1.6k 收藏
点赞数
分类专栏： C语言编程规范 文章标签： c语言 代码规范 设计规范 开发语言
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_42107504/article/details/128907121
版权

Purpose

本文用于定义程序编码规范，本文目的在于规范和指导如何进行编程活动。

Scope

本文仅用于指导软件编程工作，同时作为其他分析和设计工作的参考资料。本文的预期读者是： 软件工程师 、 架构师 、 程序员

各项项目可以采用不同的编程语言，并参照本规范和各语言习惯定义各自的编程规范，但是必须经过审核通过。编程规范一旦通过评审，任何人在变成活动中必须遵循。

Annotation

 

  • Rule 1 : 代码注释的量应该不少于总代码量的行数的 30%

Note

只有猪狗的注释才能充分的说明你的代码，没有哪个规范可以规定注释的上限，但是一般来说，30% 应该是下线。如果你的代码包括注释，空行共 90 行，那么注释应该不少于30行

  • Rule 2 : 在维护代码的同时，维护你的注释

Note

我们通常在编写代码的同时都会对代码进行注释，但是往往在维护代码的时候忘记同时维护注释。所以很多注释在代码反复修改之后，失去了说明代码的作用，这样的注释还不如不写

  • Rule 3 : 头文件注释，应扼要描述该文件完成的功能和使用约束条件

  • Rule 4 : 注释不要重复你的代码

Note

例如 String str; // 声明一个 String 对象：str 上面的代码看上去没有问题，但是注释确实没有用的–只是对代码的简单重复。要记住，注释是用来说明代码的，而不是重复代码的。

  • Rule 5 : 文件注释用于说明代码文件的一些附加信息，它位于源代码文件的顶部。文件注释最重要的作用是记录代码维护历史。

Appendix A

header 文件模板 main.h 为例

内容顺序：Marcos -> Constants -> Data Types -> Function Declarations

/*************************************************************************************************/
/*!
*  \file       main.h
*
*  \brief      BLE baseband interface file.
*
*  Copyright (c) 2011-2022 ZhuHai Jieli Technology Co.,Ltd.
*
*  Licensed under the Apache License, Version 2.0 (the "License");
*  you may not use this file except in compliance with the License.
*  You may obtain a copy of the License at
*
*      http://www.apache.org/licenses/LICENSE-2.0
*
*  Unless required by applicable law or agreed to in writing, software
*  distributed under the License is distributed on an "AS IS" BASIS,
*  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
*  See the License for the specific language governing permissions and
*  limitations under the License.
*/
/*************************************************************************************************/

#ifndef MAIN_H
#define MAIN_H

#include "typesdef.h"

#ifdef __cplusplus
extern "C" {
#endif

/*! \addtogroup MAIN_API
*  \{ */

/**************************************************************************************************
Macros
**************************************************************************************************/

/*! \brief      Returns the minimum of two values. */
#define MIN(a,b)        ((a) < (b) ? (a) : (b))

/*! \brief      Returns the maximum of two values. */
#define MAX(a,b)        ((a) > (b) ? (a) : (b))

/**************************************************************************************************
Constants
**************************************************************************************************/

/*! \brief      Operation types. */
typedef enum
{
    BB_BLE_OP_TEST_TX,                /*!< Continuous Tx test mode. */
    BB_BLE_OP_TEST_RX,                /*!< Continuous Rx test mode. */
    BB_BLE_OP_MST_ADV_EVENT,          /*!< Master advertising event. */
    BB_BLE_OP_SLV_ADV_EVENT,          /*!< Slave advertising event. */
    BB_BLE_OP_MST_CONN_EVENT,         /*!< Master connection event. */
    BB_BLE_OP_SLV_CONN_EVENT,         /*!< Slave connection event. */
    BB_BLE_OP_MST_AUX_ADV_EVENT,      /*!< Master auxiliary advertising event. */
    BB_BLE_OP_SLV_AUX_ADV_EVENT,      /*!< Slave auxiliary advertising event. */
    BB_BLE_OP_SLV_PER_ADV_EVENT,      /*!< Slave periodic advertising event. */
    BB_BLE_OP_MST_PER_SCAN_EVENT,     /*!< Master periodic scanning event. */
    BB_BLE_OP_MST_CIS_EVENT,          /*!< Master CIS event. */
    BB_BLE_OP_SLV_CIS_EVENT,          /*!< Slave CIS event. */
    BB_BLE_OP_MST_BIS_EVENT,          /*!< Master BIS event. */
    BB_BLE_OP_SLV_BIS_EVENT,          /*!< Slave BIS event. */
    BB_BLE_OP_NUM                     /*!< Total number of operations. */
} BbBleOp_t;

/*! \brief      Maximum request PDU length (MAX(LL_SCAN_REQ_PDU_LEN, LL_CONN_IND_PDU_LEN)). */
#define BB_REQ_PDU_MAX_LEN          (LL_ADV_HDR_LEN + LL_CONN_IND_PDU_LEN)

/*! \brief      Minimum scan time to cover one advertise data exchange. */
#define BB_MIN_SCAN_US              (LL_ADV_PKT_MAX_USEC  + LL_BLE_TIFS_US + \
                                    LL_SCAN_REQ_MAX_USEC + LL_BLE_TIFS_US + \
                                    LL_SCAN_RSP_MAX_USEC + \
                                    BbGetSchSetupDelayUs())

/**************************************************************************************************
Data Types
**************************************************************************************************/

/*! \brief Common message structure passed to event handler */
typedef struct
{
uint16_t        param;          /*!< \brief General purpose parameter passed to event handler */
uint8_t         event;          /*!< \brief General purpose event value passed to event handler */
uint8_t         status;         /*!< \brief General purpose status value passed to event handler */
} sysMsgHdr_t;


/**************************************************************************************************
Function Declarations
**************************************************************************************************/


/*************************************************************************************************/
/*!
*  \brief  Compare two BD addresses.
*
*  \param  pAddr1  First address.
*  \param  pAddr2  Second address.
*
*  \return TRUE if addresses match, FALSE otherwise.
*/
/*************************************************************************************************/
bool_t foo_1(const uint8_t *pAddr1, const uint8_t *pAddr2);

/*! \} */    /* MAIN_API */

#ifdef __cplusplus
};
#endif

#endif /* MAIN_API_H*/

source 文件模板 main.c 为例

内容顺序：Marcos -> Constants -> Global Variables -> Functions

/*************************************************************************************************/
/*!
*  \file       Main.c
*
*  \brief      Main file for example
*
*  Copyright (c) 2011-2022 ZhuHai Jieli Technology Co.,Ltd.
*
*  Licensed under the Apache License, Version 2.0 (the "License");
*  you may not use this file except in compliance with the License.
*  You may obtain a copy of the License at
*
*      http://www.apache.org/licenses/LICENSE-2.0
*
*  Unless required by applicable law or agreed to in writing, software
*  distributed under the License is distributed on an "AS IS" BASIS,
*  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
*  See the License for the specific language governing permissions and
*  limitations under the License.
*/
/*************************************************************************************************/

#include "typedef.h"
#include <string.h>
#include "main.h"

/**************************************************************************************************
Macros
**************************************************************************************************/
#define ARRAY_MAX_LEN       8


/**************************************************************************************************
Global Variables
**************************************************************************************************/
static unsiged char *static_var;   /*!< static varaible. */

uint8_t *golbal_var;               /*!< golbal varaible. */

/*! \brief      example array buffer. */
uint8_t array[ARRAY_MAX_LEN]



/**************************************************************************************************
Functions
**************************************************************************************************/

/*************************************************************************************************/
/*!
*  \brief  Copy a BD address from source to destination.
*
*  \param  pDst    Pointer to destination.
*  \param  pSrc    Pointer to source.
*/
/*************************************************************************************************/
static void foo(uint8_t pDst, const uint8_t *pSrc)
{
    /*Copy the source address content to the destination*/

    return 0;
}

/*************************************************************************************************/
/*!
*  \brief  Compare two BD addresses.
*
*  \param  pAddr1  First address.
*  \param  pAddr2  Second address.
*
*  \return TRUE if addresses match, FALSE otherwise.
*/
/*************************************************************************************************/
bool_t foo_1(const uint8_t *pAddr1, const uint8_t *pAddr2)
{
    return (memcmp(pAddr1, pAddr2, BDA_ADDR_LEN) == 0);
}

/*************************************************************************************************/
/*!
*  \brief  Main entry point.
*/
/*************************************************************************************************/
int main(void)
{

    /*Does not return*/
    return 0;
}

Appendix B

如在linux 环境通过vim编程，以上注释可以配置Vim 实现快速注释，可将以下快捷键 拷贝到Vimrc 配置下

inoremap xx<CR> /*!< */<Esc>F a
inoremap xc<CR> /* */<Esc>F a
inoremap xv<CR> /*! \brief      x */<Esc>Fxxi
卓学电子
关注
  • 0
    点赞
  • 踩
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
比较权威的代码注释规范（各种语言）
09-18
比较权威的代码注释规范（各种语言）比较权威的代码注释规范（各种语言）
Doxygen代码注释规范.docx
07-15
Doxygen 代码注释规范 Doxygen 是一种开源跨平台的，以类似 JavaDoc 风格描述的文档系统，完全支持 C、C++、Java、Objective-C 和 IDL 语言，部分支持 PHP、C#。Doxygen 可以从一套归档源文件开始，生成 HTML 格式...
代码注释该怎么写才规范？
最新发布
strongerHuang
04-24 263
关注+星标公众号，不错过精彩内容编排 |strongerHuang微信公众号 |strongerHuang如果领导给你一个项目的源码让你阅读，并理解重构代码，但里面一句注释都没有，我想这肯定是之前同事“删库跑路”了。看一份源码什么很重要？除了各种代码规范之外，还有一个比较重要的就是注释。注释虽然写起来很痛苦, 但对保证代码可读性至关重要，下面的将描述如何注释以及在哪儿注释。注释风格1.总述一般...
【代码规范】常见注释规范
一蓑烟雨任平生
12-26 3153
1.在有处理逻辑的代码中，源程序有效注释量必须在20％以上。 说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 2.文件注释：文件注释写入文件头部。 说明：以/* 开始 示例： / * * 文件名：[文件名] * 作者：〈版权〉 * 描述：〈描述〉 * 修改人：〈修改人〉 * 修改时间：YYYY-MM-DD * 修改内容：〈修改内容〉 */ 说明：每次修改后在文件头部写明修改信息。 示例： / *
代码注释规范整理
Y2567326540的博客
05-22 5354
转载自51CTO大佬yuke198907 原文章地址：https://blog.51cto.com/yuke198907/1300804（侵删） 版权这个很重要 程序中的注释是程序设计者与程序阅读者之间通信的重要手段。应用注释规范对于软件本身和软件开发人员而言尤为重要。并且在流行的敏捷开发思想中已经提出了将注释转为代码的概念。好的注释规范可以尽可能的减少一个软件的维护成本，并且几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护。好的注释规范可以改善软件的可读性，可以让开发人员尽快而彻底地
总结之java代码规范（一）——注释规范、IDEA类和方法注释模板设置
IManiy的博客
06-15 2388
最近新团队需要需要整一套适合java代码规范，基于阿里java开发手册规范一下代码规范。
Java代码注释规范(动力节点整理)
08-30
Java代码注释规范是编程实践中不可或缺的一部分，它有助于提高代码的可读性和团队协作效率。以下是一些关于Java代码注释的基本原则和建议： 1. **注释形式统一**： - 在整个代码库中，应保持注释风格的一致性。这...
Doxygen代码注释规范
02-06
"Doxygen代码注释规范" Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。Doxygen可以从一套归档源文件开始，生成HTML格式的在线类...
代码注释规范之doxygen
11-19
Doxygen是一个程序的文档产生工具，可以将程序中的注释转换成说明文档或者说是API参考手册，从而减少程序员整理文档的时间。
Python代码注释规范代码实例解析
09-16
Python代码注释是提高代码可读性和维护性的重要手段，良好的注释规范能让代码更易于理解和维护。本文将深入探讨Python代码注释的规范及其实例解析。 首先，注释的目的是为了帮助开发者理解代码的功能和逻辑，尤其...
代码注释规范_python3_javascript
06-18
2. 注释里的URL 不要使用反斜杠连接行. Python会将 圆括号, 中括号和花括号中的行隐式的连接起来 , 你可以利用这个特点. 如果需要, 你可以在表达式外围增加一对额外的圆括号. Yes: foo_bar(self, width, height, ...
关于PHPDocument 代码注释规范的总结
10-27
本篇文章是对PHPDocument代码注释规范进行了详细的总结与介绍，需要的朋友参考下
Java代码注释规范详解
09-02
Java代码注释是编程实践中不可或缺的一部分，它有助于提高代码的可读性和维护性。...当团队成员都能遵循一致的注释规范时，代码质量会显著提高，项目也更容易管理。因此，投入时间和精力编写良好的注释是值得的。
php DOC类型注释的用法
weixin_34375054的博客
08-04 235
/*** @name 名字* @abstract 申明变量/类/方法* @access 指明这个变量、类、函数/方法的存取权限* @author 函数作者的名字和邮箱地址* @category 组织packages* @copyright 指明版权信息* @const 指明常量* @deprecate 指明不推荐或者是废弃的信息* @example 示例* @exclude 指明当前的注释将...
3、代码注释与编码规范
PY洋洋
01-15 695
一、代码注释 （1）单行注释 （2）多行注释 （3）文档注释 2. 编码规范
python代码注释规范
10-04
PEP 8是Python代码规范的官方指南。它提供了全面的代码格式和注释建议。在Python中，注释是用来解释代码功能和提供上下文的重要工具。以下是一些关于Python代码注释规范的要点： 1. 单行注释应该以 # 开头，而多行注释应该使用 """ 或 ''' 包围。多行注释通常用于对整个函数或类进行解释。 2. 注释应该用简洁和明确的语言来解释代码的功能、原理或关键思路。 3. 注释应该是可读性强的，避免使用复杂的技术术语或不必要的细节。 4. 注释应该与代码保持同步更新。如果你修改了代码逻辑，记得同时更新相关的注释。 5. 对于简单明了的代码，可以不添加注释。注释应该用于解释复杂或难以理解的代码。 6. 注释应该距离代码至少2个空格，以提高可读性。 7. 不要描述代码的功能，假设读代码的人比你更懂Python。注释应当解释代码的作用和目的。 8. 注释应该使用英文，以确保代码的可移植性和可理解性。 9. 遵守PEP 8代码格式的其他规则，如缩进、命名规范等。这些规则可以提高代码的可读性和一致性。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值