android studio代码注释模版 安卓代码注释

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 配置下

i

noremap xx<CR> /*!< */<Esc>F a
inoremap xc<CR> /* */<Esc>F a
inoremap xv<CR> /*! \brief      x */<Esc>Fxxi