欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  后端开发

你们觉得一份代码,注释和代码的比例应该是怎么样的一个范围空间比较合适,可以是字节角度,也可以是行数角度?

程序员文章站 2022-05-28 13:09:58
...

回复内容:

国标规定,VC工程注释率为25%~50%,关键代码注释率为50%;

不满足要求就无法通过软件三方测评;

在满足这个要求的前提下再谈哪些需要注释。

为了增加代码注释率,减少三方测评前“脑补”注释的痛苦,
我们一般要求把《软件设计文档》中的"关键算法”、“接口数据定义”等内容直接拷贝到代码前面;

修改代码时也顺便把”关键算法“、“接口数据定义”等的注释也修改了;

修编《软件设计文档》时再用注释中的”关键算法“、“接口数据定义”等内容替换文档中的相关内容;

通过这种办法来保证文档和代码的一致性,减少软件维护与人员更换时痛苦…… 我的观点,只写说明性注释,不写功能性注释。也就是说,注释Why,而不是How和What

类和函数多写文档注释,多少行无所谓,写在最前面,只要你是注释的Why。

函数内部,尽量少写注释。如果你的代码需要写注释来说明他的功能,那么这段代码就需要重构,最简单的方法,最简单的方法:提取函数。这样的好处是,函数名就是注释。一个错误的观点就是 注释是给人看的,程序是给电脑看的。其实,程序是给人的,凑巧的是,它居然可以在电脑里运行。

《重构:改善既有代码的设计》一书写道:
每当感觉需要以注释来说明点什么的时候,我们就把需要说明的东西写进一个独立函数中,并以其用途(而非实现手法)命名
每次我给别人讲解「选择排序」、「插入排序时」,他们都觉得太难了,而且几乎每本数据结构教科书都是写了一堆代码和注释,这丝毫没有降低这个算法的难度。

如果不写注释,而写成函数呢?

伪代码:
array_ordered = []
loop_all_element(array, function(i){
el = select(array[i+1, array.length])
push(array_ordered, el)
......
})
  1. 构建一个有序数组,初始为空
  2. 循环整个数组,进行如下操作:
  3. 从数组剩下的元素里面选择最小的(或最大的)
  4. 将最小元素放在有序数组的最后面(或者最前面)
不用我多解释,你一眼就知道,这是选择排序

插入排序呢?大同小异,我就不详细写了。

所以,文档注释,多少无所谓。函数内、类内注释,能不写,就不写。 我是这样看的,要看你写的代码的作用是什么。
1.简单代码或脚本,遵循命名规范,可以不写注释,文件开始写明作用即可。关键部分写简单注释。
2.由多个文件组成的复杂项目结构,文件开始的说明最好由工具生成,类方法的输入输出要标明。
3.如果是开源项目,那情况又完全不一样了,注释简直是越多越好,“为什么这么做”也越多越好。

以上是我的理解,还请各位指正 PHP本身,并不需要什么注释
变量命名规范一点就行。
最多给每个方法给一段说明。