手把手教你写_“华为”_的标准注释与文档,以及代码规范

本文详细阐述了在编程中注释和文档的重要性,包括注释的规范、比例、内容要求,以及代码规范,强调了注释应清晰、准确,避免二义性,并提倡边写代码边注释,保证代码与注释的一致性。同时,文章提到了代码规范对于提高代码可读性和开发效率的作用。
摘要由CSDN通过智能技术生成

注释


为什么要写注释呢?为什么要写文档呢?
也许有人会这样问。但是我只想说如果你还在这样问,那么你不仅不是一个优秀的程序员,应该说你是不是程序员都应该受到质疑。

先说一下注释的重要性:
在公司的开发中,我们要明白程序不是写给自己看的,也不是所有的代码都是自己写的,我们不仅需要看别人的代码而且还要把自己的代码交给别人看,团队看。也许还会在你离职以后交给你的接班人看。而且,就算是你写的程序,如果过了很久你再去看的话(相信也会受到一万点真实伤害,脱口而出”这是哪个家伙写的这是什么东西!!!”)所以,程序文档的书写,注释的书写,以及标准的编码规范就非常的重要。(而这些是每一个大学老师都不会交给你的)

  • 一般情况下,源程序的有效注释量必须在20%以上。
    说明:注释的原则是有助于对程序的阅读理解,在该加的地方都加上,注释不宜太多。也不能太少。注释语言必须准确、易懂、简洁

  • 说明性文件(如头文件.h文件、inc文件、.def文件、编译说明文件.cfg等)头部应该进行注释,注释必须列出:版本说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等,头文件的注释还应有函数功能简要说明
    示例(本人的头文件头注释,当然并不局限此格式):
    这里写图片描述

  • 源文件头部应进行注释,列出:版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。
    示例(本人源文件头注释,不局限与此格式)
    这里写图片描述
    说明:Description一项描述本文件的内容、功能、内容各部分之间的关系及本文件与其他文件关系等。History是修改历史列表,每条记录应包括修改日期、修改人、修改内容简述等。

  • 函数头部进行注释,例出:函数的目的/功能、输入参数、输出参数、返回值、调用关系(函数、表)等。
    示例:(本人的函数头注释,不局限与此格式)
    这里写图片描述

  • 我们应该养成边写代码边注释的习惯,修改代码同时修改相应的注释,以保证注释与代码的一致性。不再有用的注释要删除

1、清晰第一 清晰性是易于维护、易于重构的程序必需具备的特征。代码首先是给人读的,好的代码应当可以像文章一样发声朗诵出来。 目前软件维护期成本占整个生命周期成本的40%~90%。根据业界经验,维护期变更代码的成本,小型系统是开发期的5倍,大型系统(100万行代码以上)可以达到100倍。业界的调查指出,开发组平均大约一半的人力用于弥补过去的错误,而不是添加新的功能来帮助公司提高竞争力。 一般情况下,代码的可阅读性高于性能,只有确定性能是瓶颈时,才应该主动优化。 2、简洁为美 简洁就是易于理解并且易于实现。代码越长越难以看懂,也就越容易在修改时引入错误。代码越多,意味着出错的地方越多,也就意味着代码的可靠性越低。因此,我们提倡大家通过编简洁明了的代码来提升代码可靠性。 废弃的代码(没有被调用的函数和全局变量)要及时清除,重复代码应该尽可能提炼成函数。 3、选择合适的风格,与代码原有风格保持一致 产品所有人共同分享同一种风格所带来的好处,远远超出为了统一而付出的代价。在公司已有编码规范的指导下,审慎地编排代码以使代码尽可能清晰,是一项非常重要的技能。 如果重构/ / 修改其他风格的代码时,比较明智的做法是根据 现有 代码 的 现有风格继续编代码,或者使用格式转换工具进行转换成公司内部风格。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

zxnsirius

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

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

余额充值