以 java 为例: 使用 swagger 做为文档工具。
注释目前只在接口上写,不在实现类和 sql xml 上写。
入参对象参数注释都在 Query Object 上用 swagger 写注释。
java doc 参考的是阿里巴巴代码规范注释规约
1
TomatoYuyuko 2020-07-28 14:17:21 +08:00
有本书叫代码整洁之道
|
2
specita 2020-07-28 15:11:55 +08:00
注释我不会嫌多的
|
3
sugars 2020-07-28 15:15:35 +08:00
注释尽管写,反正前端打包编译时可以移除掉
|
4
pushback 2020-07-28 15:23:00 +08:00
|
5
qq976739120 2020-07-28 15:27:07 +08:00
注释多比少好,越多越好,多了我会自己过滤掉多余信息,少了是真的只能硬着头皮看代码,另外,注释和代码不一致更蛋疼
|
6
puzzle9 2020-07-28 17:13:09 +08:00 via Android
记得在知乎看到
注释是 我的代码为何这么做 而不是表达 我的代码做了什么 |
7
optional 2020-07-28 17:16:41 +08:00 via iPhone
不写注释。
|
8
wzzzx 2020-07-28 17:22:57 +08:00
公司的大佬说,注释本质上就是代码的冗余,也是需要维护的。所以要多写一些让人能看懂的代码,就可以不用写注释了
|
9
DiamondY 2020-07-28 17:24:30 +08:00
注释为啥是越多越好?我以前看过一些注释啰嗦到像流水账和日记一样,看得贼尴尬
|
10
aguesuka 2020-07-28 18:51:30 +08:00
|
11
xizismile 2020-07-28 19:48:04 +08:00 via Android
看一看 java 源码中的注释,你就知道哪些地方需要写了
|
12
keshawnvan 2020-07-28 21:36:58 +08:00
接口上写,实现上只有代码不能很好解释意图的地方写
|
13
no1xsyzy 2020-07-28 23:44:29 +08:00
注释越多越好?
难以阅读的代码提名奖: 在注释中讲个引人入胜的小故事 |
14
DreamSpace 2020-07-29 00:08:02 +08:00 via Android 1
写代码先写 //TODO
代码写完后把"TODO" replace 掉,剩下的就是注释 |
15
frankyzf 2020-07-29 00:09:08 +08:00
感觉注释越少越好,如果必须加很多注释可能意味着 code 的逻辑不是很清晰或者需要抽离出方法。整块复杂逻辑除外。
|
16
frankyzf 2020-07-29 00:10:09 +08:00
或者命名不够准确
|
17
jingsan0801 2020-07-31 14:59:56 +08:00
好几年前公司代码有规范说, 注释不能少于代码量的 30%;
后来才明白好的代码是不需要注释的, 好的代码是能做到自注释的 要写注释的情况是因为代码不能明确说明程序的逻辑, 而且注释应该是对业务逻辑的说明, 而不是代码逻辑. |