语言编写规范之注释
-------------------------------------------------------
1. 注释原则
1.1 项目开发中,尽量保持代码注释规范和统一。
1.2 注释方便了代码的阅读和维护。
1.3 边写代码边注释,修改代码时要相应修改注释,保证注释和代码的一致性。
1.4 注释要简洁明确,不要出现形容词。
1.5 通过注释可以快速知道所写函数的功能,返回值,参数的使用。
2. 文件头部注释
/********************************************************************************
* @File name: biu.c
* @Author: Tobiubiu
* @Version: 1.1
* @Date: 2017-5-24
* @Description: The function interface。
********************************************************************************/
还可以增加:版权说明等。
3. 结构体、全局变量等的注释
int num; /*全局变量的作用*/
/*结构体的功能*/
typedef struct{
int h; /*High risk*/
int l; /*Low risk*/
int m; /*Middle risk*/
int i; /*Information risk*/
}risk;
4. 函数的注释
函数头部应进行注释,列出:函数的目的/功能、输入参数、输出参数、返回值、调用关系(函数、表)等
/*******************************************************
*
* Function name :insert_hhistory
* Description : Insert to bd_host_history
* Parameter :
* @ipsql SQL statement
* @host_level Risk level
* @total The total number of risk
* @t_id task id
* @t_uuid task uuid
* @ipaddr target ipaddr
* @end_time task end time
* Return :0 success , other fail
**********************************************************/
int insert_hhistory(char* ipsql,risk host_level,int total,int t_id,char* t_uuid,char* ipaddr,long int end_time)
{
/*
* 如果程序过于复杂,这里可以写明,具体算法和思路。
*/
}
5. 建议
5.1 一般情况下,源程序有效注释量必须在20%以上。 注释不宜太多、不宜太少,准确易懂简洁;
5.2 注释格式尽量统一,建议使用“/* …… */”;
5.3 避免在一行代码或表达式的中间插入注释;
说明:除非必要,不应在代码或表达中间插入注释, 否则容易使代码可理解性变差。
5.4 通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成为自注释的。
说明:清晰 准确的函数、变量等的命名,可增加代码可读性,并减少不必要的注释。
5.5 在代码的功能、意图层次上进行注释,提供有用、额外的信息。
说 明:注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。
相关推荐
嵌入式状态机编程-QP状态机框架与常见状态机方法
状态机基本术语 现态:是指当前所处的状态。 条件:又称为“事件”,当一个条件被满足,将会触发一个动作,或者执行一次状态的迁移。 动作:条件满足后执行的动作。动作执行完毕后,可以迁移到新的状态,也可以仍旧保持原状态。动作不是必需的,当条件满足后,也可以不执行任何动作,直接迁移到新状态。 次态:条件满足后要迁往的新状态。“次态”是相对于“现态”而言的,“次态”一旦被激活,就转变成新的“现态”了。 传统有限状态机Fsm实现方法 如图,是一个定时计数器,计数器存在两种状态,一种为设置状态,一种为计时状态 设
C语言代码注释规范
*** 函数名() - 函数简要说明.* @参数1: 描述第一个参数.* @参数2: 描述第二个参数.* 可以为参数提供一段* 多行描述.* 更详细的描述,进一步讨论函数 函数名(), 这可能对使用或修改它的人有用.* 以空注释行开始, 内部可以包含空注释行.* 详细描述可以有多个段落.* Context: 描述函数是否可以休眠, 它需要、释放或期望持有什么锁.* 可以写多行.
Linux中断子系统(二)—— 通用框架处理
1、数据结构分析 (1)中断描述符结构structirq_desc: 1)打开CONFIG_SPARSE_IRQ宏(中断编号不连续),中断描述符以radix- tree来组织,用户在初始化时进行动态分配,然后再插入radix-tree中; 2)关闭CONFIG_SPARSE_IRQ宏(中断编号连续),中断描述符以数组的 形式组织,并且已经分配好; 3)不管哪种形式,最终都可以通过linuxirq号来找到对应的中断描述符; (2)stru...
C/C++代码规范注释有哪些讲究?
关注、星标公众号,不错过精彩内容编排 |strongerHuang微信公众号:strongerHuang如果领导给你一个项目的源码让你阅读,并理解重构代码,但里面一句注释都没有,我想这...
基于ENVI5.3的Landsat条带去除、辐射定标、大气校正
基于ENVI5.3的Landsat条带去除、辐射定标、大气校正坏带修复辐射定标大气校正 坏带修复 1.下载landsat_gapfill插件,放入“安装目录\Exelis\ENVI53\extensions”,重启ENVI 2. 加载拟处理文件(MTL.txt格式) 3.打开landsat_gapfill 4.选择存放位置并命名文件 5.选择处理文件 辐射定标 1.选择工具Radiometric Calibration 2.选择已修复坏带文件 3.修改参数,选择输出位置及命名文件 大气校正 1
vietjetair 航空的webpack多参数生成学习
工作内不是特别多,居安思危,有一个抓机票信息的公司面试前竟然需要做面试题,这就是一个题。看了下,有点麻烦,webpack 最初不得要领,看了下资料,找了个框架,练了两个简单的,搞这个吧。入库需要自己找,有几个参数不是明文的,算法不是很复杂,位置不太好找。整体难度一般。
【C语言基础】编程规范——注释
①、规范的注释模板之一 1、头文件的头部注释 /** * Copyright (C), 2020-2020, github.com/XIN-Mr. * File name: test.h // 文件名 * Author:XIN-Mr Version:V1.0 Date:2020.8.5 // 作者、版本及完成日期 * Description: // 用于详细说明此程序文件完成的主要功能,与其他模块 // 或函数的接口,输出值...
Win11下Android模拟器报HAXM未安装?三步搞定虚拟化配置(附终端命令)
本文详细解析了Win11下Android模拟器HAXM报错的解决方案,从虚拟化配置到终端命令实战。通过检查BIOS设置、调整Windows功能及执行PowerShell命令,三步搞定虚拟化配置问题,有效提升模拟器性能。特别针对Win11与HAXM的兼容性问题提供了专业指导。
【C语言】C语言代码的编写规范、注释规范
提示:以下是本篇文章正文内容,下面案例可供参考本文仅仅简单介绍了【C语言】C语言代码规范,评论区欢迎讨论。
【机器学习】【期末复习】有关机器学习的计算题可供期末复习参考(带本人手写解答与思考)
本文为学校课程《机器学习》的期末复习材料,主要是关于一些机器学习模型的计算题的解答过程。
基于STM32L4XX、HAL库的AD7124-8BCPZ模数转换器ADC驱动程序设计
/ 公式: Voltage = (adc_value / (2^23 - 1)) * Vref。// 模式控制位[7:5]=000 (连续转换模式)// 3.2 配置通道0,使其使用AIN0(+)和AIN1(-),并关联到配置0和滤波器0。= 0x14) { // AD7124-8的ID是0x14。// 双极性操作,缓冲AINP/AINN。
c语言模块 文件 级注释,C语言 - 基于STM32库文件编写符合Doxygen规范的注释
C语言 - 基于STM32库文件编写符合Doxygen规范的注释C语言 - 基于STM32库文件,编写符合Doxygen规范的注释写了这么多,其实还是不知道怎么去写注释。我们知道stm32库文件是符合库文件标准,那么我们就参照它的注释格式,来编写我们的注释文件。为了能使代码能够被Doxygen识别,必须遵循Doxygen的书写规则。注释必须以/**打头,以*/结束。一、添加类型1、添加首页(m...
AI Agent Harness与SCADA系统集成
简单来说,AI Agent Harness是Industrial AI Agent的“中央调度室+装备库+知识库+安全网”把不同技术栈、不同部署环境(云/边/端)、不同功能(感知、推理、决策、执行、验证)的“零散Agent”组装成具备特定工业场景能力的Agent Team(如聚合反应根因诊断Agent Team);管理Agent Team的生命周期(创建、初始化、调度、监控、销毁);提供统一的工业多工具调用接口(对接SCADA、MES、PLC、DCS、巡检机器人、数字孪生平台等);内置。
C语言 - 基于STM32库文件,编写符合Doxygen规范的注释
写了这么多,其实还是不知道怎么去写注释。我们知道stm32库文件是符合库文件标准,那么我们就参照它的注释格式,来编写我们的注释文件。 为了能使代码能够被Doxygen识别,必须遵循Doxygen的书写规则。注释必须以/**打头,以*/结束。 一、添加类型 1、添加首页(mainpage): 格式: /** \mainpage RIOM DSP Software Library...
C# WinForm 基于DirectShow.dll编写的程序,可边预览边保存视频,音频和图片
基于微软的DirectShow.dll的二次开发1.自动识别连接的摄像头跟麦克风且可以对其进行选择(默认选中第一个)2.可录制wmv和avi两种格式的视频并且都带有音频,avi可以录制的分辨率和帧数进行选择,wmv默认进行了淸晰度优化如不喜欢可去除代码中有相关提示3.可在预览点开之后进行拍照,也可边录制视频边拍照4.添加了视频和音频的压缩功能(酌情使用)这次二次开发发现C#对DirectShow的相关信息太少,这次做完也不敢藏私共享出来,还望大家指正
ssm框架搭建
这个是一个在idea上成功跑起来的ssm框架项目,保存在这里方便以后使用直接下载
【C语言教程】代码规范和文档编写
学习C语言的进阶部分不仅仅是掌握更多的语法,而是深入了解语言的特性,提高思维的广度和深度,这对编写高效、健壮的程序至关重要。本教程旨在帮助读者实现从基础到高级的C语言编程能力转变,特别关注以下几个方面:目标介绍本教程的目标是:在接下来的章节中,会涵盖C语言高级用法和最佳实践,帮助读者避免常见错误,提高工程项目的设计水平。让我们从C语言的代码规范和文档编写开始,逐步进入更复杂的话题。以下是详细提纲及内容讲解。在编写C语言代码时,遵循一定的编码规范不仅有助于提升代码的可读性和可维护性,还能减少由于风格不一致而导
迈瑞BS系列全自动生化分析仪LIS协议接口手册(内含HL7和ASTM)
迈瑞BS系列全自动生化分析仪LIS协议接口手册,内含HL7和ASTM)
C代码编写规范
c的一些规范
Devexpress16.2.6破解工具
Devexpress16.2.6破解工具Devexpress16.2.6破解工具Devexpress16.2.6破解工具Devexpress16.2.6破解工具
嵌入式C编程规范
背景 C语言是嵌入式开发常用的语言工具,C程序员都知道C是一种灵活而强大的语言,另一方面强大的功能也带来一定的复杂性,并使代码出现bug或者难以维护。这份编程规范的目的在于通过规范哪些可以做哪些不可以做来管理C代码的复杂性,同时在可管理的基础上提高大家使用C语言的生产力。 编程规范,英文style,也可以叫做代码的可读性,是一种通过一些规范来管理我们代码的方法。我们保持代码可管理的基础
大厂C语言编写、测试、维护、审查规范
本规范旨在统一 C 语言编码标准,提升代码的可读性、可维护性、可测性与稳定性,覆盖从代码排版到宏定义的全流程开发环节
华为C语言编程规范(精华总结)
目录 1、代码总体原则 2、头文件 2、函数 3、标识符命名与定义 4、变量 5、宏、常量 6、表达式 7、注释 8、排版与格式 9、代码编辑编译 “编写程序应该以人为本,计算机第二。” ...
嵌入式C语言代码编写规范
嵌入式C语言代码编写规范 【下载地址】嵌入式C语言代码编写规范分享 本仓库提供了一份详细的嵌入式C语言代码编写规范资源文件,旨在帮助嵌入式开发人员编写更加规范、高效、可维护的代码。该规范涵盖了代码风格、命名规则、注释规范、函数设计、内存管理等多个方面,适用于各种嵌入式系统开发项目 ...
C1.C语言规范_V1.1
1.简介 代码编写规则应该在建立在一个工程项目之前。该规则应该贯穿整个项目的始终以保证代码的一致性。采用标准的代码编写惯例,可大大简化项目的维护负担。在C语言中可以有多种代码的编写方法(当然其它编程序语言亦如此),你可以尽可能采用一种好的风格,以达到以下目的: 可移植 (Portability) 连贯 (Consistency) 整洁(Neatness) 易于维护(Easy Maintenance...
c语言内容编写顺序和注释、声明的作用
基于以上情况,我现在的想法是:直接到源文件中首先编写函数注释,然后编写函数头,确定返回值,函数名,参数列表,然后具体编写函数体,编写完后,如果这个函数是API函数,能够被其他源文件中函数调用,再在头文件中复制函数头,如果该函数只在源文件中被其他函数调用,使用static修饰,或者在源文件前面复制函数头,形成静态函数。,因为这种多行注释适合写注释内容比较多的情况,可以一对注释在注释内部就完成:函数注释(一句话表述某一个过程)编写,返回值是什么,参数列表是什么意思,是输入型参数还是输出型参数等等。
C语言程序基本内容
经典案例代码Hello World! 学习一门编程语言,可能最先接触的就是Hello World代码段。 源代码: #include <stdio.h> int main() { printf("Hello World!\n"); return 0; } 运行结果: Hello World! C语言程序的基本结构 头文件(预处理) C程序代码中,要想用一件东西,必须要提前说明,头文件也是如此。 上面Hello World!案例中#include <stdio.h>为包含头
c语言入门基础
C语言的结构 1、Hello world 简单来说,一个C程序就是由若干头文件和函数组成。 #include //包含头文件 /* *主函数 */ int main(){ printf(“Hello World”); return 0; } #include 就是一条预处理命令,它的作用是通知C语言编译系统在对C程序进行正式编译之前需做一些预处理工作。 函数就是实现代码逻辑的一个小的单元。 注:在最新的C标准中,main函数前的类型为int而不是void。 2、主函数 一个C程序有且只有一个主函数,即mai
C语言编程基础(1)注释风格、编程规范、常量变量
对于C语言编程者尤其是C语言初学者是否遇到过自己编写的代码几个月之后自己都看不懂了呢?功能实现后回头一看代码显得杂乱无章呢?变量与常量的使用规则是否还有点模糊不清呢?本章节将介绍C语言编程的注释风格,编程规范和C语言中的常量与变量。 1、 C语言注释风格 C语言的注释主要用于项目简介、代码解释,便于时隔多日的自己或者他人能够快速理解你的代码,C语言注释不参与编译,不占用程序存储空...
编写c语言程序的规范,C语言-程序代码编写规范.doc
C语言-程序代码编写规范C语言 程序代码编写规范(初级程序员 讨论版)前言一个好的程序编写规范是编写高质量程序的保证。清晰、规范的源程序不仅仅是方便阅读,更重要的是能够便于检查错误,提高调试效率,从而最终保证软件的质量和可维护性。说明此文挡还在完善改进中,如有不足,欢迎指正。本文档主要适用于刚刚开始接触编程的初学者。对于具有一定工程项目开发经验的程序员,建议学习C语言程序代码编写规范—高级版。目录...
9667



被折叠的 条评论
为什么被折叠?



