语言编写规范之注释
-------------------------------------------------------
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 在代码的功能、意图层次上进行注释,提供有用、额外的信息。
说 明:注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。
相关推荐
STM32F030F4P6实战:LL库+DMA驱动WS2812全流程(附避坑指南)
本文详细介绍了如何使用STM32F030F4P6的LL库和DMA驱动WS2812 LED灯带的全流程,包括硬件选型、CubeMX配置、LL库与DMA关键实现、数据格式转换及调试技巧。特别提供了避坑指南,帮助开发者避免常见错误,提升开发效率。
C语言代码注释规范
*** 函数名() - 函数简要说明.* @参数1: 描述第一个参数.* @参数2: 描述第二个参数.* 可以为参数提供一段* 多行描述.* 更详细的描述,进一步讨论函数 函数名(), 这可能对使用或修改它的人有用.* 以空注释行开始, 内部可以包含空注释行.* 详细描述可以有多个段落.* Context: 描述函数是否可以休眠, 它需要、释放或期望持有什么锁.* 可以写多行.
Optisystem软件与Matlab软件的联合数据读取
目录 Matlab软件程序编写 Optisystem软件的连接与设置 数据读取结果 Matlab软件程序编写 利用Matlab软件按照下图编写程序,保存为getdata.m文件。 OutputPort1 =InputPort1; fileID=fopen('OSAdata.txt','wt'); fprintf(fileID,'%f\n',OutputPort1.Sampled.Signal); fclose(fileID); Optisystem软件的连接与设置 (以基于线性插值法
C/C++代码规范注释有哪些讲究?
关注、星标公众号,不错过精彩内容编排 |strongerHuang微信公众号:strongerHuang如果领导给你一个项目的源码让你阅读,并理解重构代码,但里面一句注释都没有,我想这...
别只当玩具!聊聊这个555金属探测器电路背后的电磁感应与RLC调谐原理
本文深入解析了555金属探测器电路的工作原理,重点探讨了电磁感应与RLC调谐原理。通过分析电感线圈的电磁特性、RLC谐振电路的行为以及555定时器的多重功能,揭示了这一看似简单的装置如何实现金属检测。文章还提供了灵敏度优化方案和常见问题解决方法,帮助读者从科学角度理解这一实用技术。
【Docker安装】Ubuntu 24.04.2 LTS系统下安装Docker环境——指定APT源安装方式
【Docker安装】Ubuntu 24.04.2 LTS系统下安装Docker环境——指定APT源安装方式
【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: // 用于详细说明此程序文件完成的主要功能,与其他模块 // 或函数的接口,输出值...
虚拟机VMware Horizon Client与主机之间建立共享文件夹
因经常需要在虚拟机和主机之间传递一些日常文件,所以建立共享文件夹。 虚拟机中安装的系统为win10,主机中的系统为win10。 步骤: 第一步:先在虚拟机win10中新建文件夹(我重命名为“共享文件夹”),然后右键属性->共享->共享 进去之后点击自己的账户名 然后点共享。操作完成后,再返回属性界面就能看到该文件夹已经共享而且出现了共享链接,记下此链接。 第二步:回到主机桌面->此电脑->最上面计算机->添加一个网络位置- 点击下一步 然后自定义网络位置,下一步,如下图
【C语言】C语言代码的编写规范、注释规范
提示:以下是本篇文章正文内容,下面案例可供参考本文仅仅简单介绍了【C语言】C语言代码规范,评论区欢迎讨论。
基于STM32、HAL库的CH9434总线转UART驱动程序设计
CH9434是一款USB转4串口控制芯片,可以将单个USB接口扩展为4个独立的串口(UART)。支持多种数据格式(数据位5-8,停止位1/1.5/2,奇偶校验或无校验)// 读取接收到的数据。// 重新启动接收中断。// 向所有4个串口发送数据。// UART初始化函数示例(USART1)// 其他UART初始化函数类似...// 初始化CH9434。// 初始化UART1。// 初始化UART2。// 初始化UART3。// 初始化UART4。工作电压:3.3V/5V兼容。
OpenClaw实战系列01:OpenClaw接入飞书机器人全接入指南 + Ollama本地大模型
通过 OpenClaw + Ollama + 飞书的组合,我们成功搭建了一个完全私有、免费、可定制的AI助理。它不仅能在日常聊天中提供帮助,还能通过OpenClaw强大的“技能”体系,真正去操作你的电脑、管理文件、甚至执行代码。这套方案将数据留在本地,既保证了隐私安全,又锻炼了动手能力。现在,去给你的AI助理添加更多酷炫的技能吧!
c语言模块 文件 级注释,C语言 - 基于STM32库文件编写符合Doxygen规范的注释
C语言 - 基于STM32库文件编写符合Doxygen规范的注释C语言 - 基于STM32库文件,编写符合Doxygen规范的注释写了这么多,其实还是不知道怎么去写注释。我们知道stm32库文件是符合库文件标准,那么我们就参照它的注释格式,来编写我们的注释文件。为了能使代码能够被Doxygen识别,必须遵循Doxygen的书写规则。注释必须以/**打头,以*/结束。一、添加类型1、添加首页(m...
Unity 热更新技术 | (二) AssetBundle - 完整系列教程学习
开始学习热更新方面系列知识,就从这一篇开始吧! 本系列教程 会从热更新基本概念出发,详细介绍热更新相关的全套知识点。 如热更新技术基本原理、热更新主流方案、AssetBundle系列教程、Lua语言编程、Lua与Unity交互教程、Xlua框架使用、热更新实战教程等方面。 热更新作为一个开发者必备技能,如果想学习的话,可以从现在开始了哦~ 接下来从 AssetBundle - 完整系列教程学习 开始学习吧!
C语言 - 基于STM32库文件,编写符合Doxygen规范的注释
写了这么多,其实还是不知道怎么去写注释。我们知道stm32库文件是符合库文件标准,那么我们就参照它的注释格式,来编写我们的注释文件。 为了能使代码能够被Doxygen识别,必须遵循Doxygen的书写规则。注释必须以/**打头,以*/结束。 一、添加类型 1、添加首页(mainpage): 格式: /** \mainpage RIOM DSP Software Library...
jdk-8u144-linux-x64.tar.gz.
该资源为搭建Linux系统Java环境用,资源的后缀为tar.gz格式的压缩包
Camera2Demo
在Camera2 的基础上进行封装,使得Camera2一堆初始化逻辑与Activity分离,降低耦合度,完成预览拍照并保存的操作
【C语言教程】代码规范和文档编写
学习C语言的进阶部分不仅仅是掌握更多的语法,而是深入了解语言的特性,提高思维的广度和深度,这对编写高效、健壮的程序至关重要。本教程旨在帮助读者实现从基础到高级的C语言编程能力转变,特别关注以下几个方面:目标介绍本教程的目标是:在接下来的章节中,会涵盖C语言高级用法和最佳实践,帮助读者避免常见错误,提高工程项目的设计水平。让我们从C语言的代码规范和文档编写开始,逐步进入更复杂的话题。以下是详细提纲及内容讲解。在编写C语言代码时,遵循一定的编码规范不仅有助于提升代码的可读性和可维护性,还能减少由于风格不一致而导
android 蓝牙通讯demo
android 下蓝牙通讯demo,实现了发现蓝牙,使能蓝牙,通过蓝牙发送消息。
C代码编写规范
c的一些规范
NTscan扫描工具
ntscan是一个扫描器,可以扫描没有密码和弱密码的共享,先到配置文件中填写猜测的用户名和密码,扫描过程中右侧出现的是扫描日志。
嵌入式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语言程序代码编写规范—高级版。目录...
487



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



