代码注释哪些地方要写？以及如何书写比较规范且不冗余

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

这是一个创建于 1611 天前的主题，其中的信息可能已经有所发展或是发生改变。

以 java 为例：使用 swagger 做为文档工具。

注释目前只在接口上写，不在实现类和 sql xml 上写。

controller
使用 swagger 注解注释，就不写 java doc 注释。

入参对象参数注释都在 Query Object 上用 swagger 写注释。

service
service 接口写 java doc 注释
- impl
  不写注释
mapper
接口上写注释
- xml(mybatis)sql
  不写注释

java doc 参考的是阿里巴巴代码规范注释规约

注释

Java

doc

swagger

17 条回复 • 2020-07-31 14:59:56 +08:00

TomatoYuyuko

2020-07-28 14:17:21 +08:00

有本书叫代码整洁之道

specita

2020-07-28 15:11:55 +08:00

注释我不会嫌多的

sugars

2020-07-28 15:15:35 +08:00

注释尽管写，反正前端打包编译时可以移除掉

pushback

2020-07-28 15:23:00 +08:00

@Deprecated 要吧，
自定义注解要吧，
method 要吧，
局部变量要吧,
内部类要吧，
yml 要吧，
iml 要吧，

qq976739120

2020-07-28 15:27:07 +08:00

注释多比少好,越多越好,多了我会自己过滤掉多余信息,少了是真的只能硬着头皮看代码,另外,注释和代码不一致更蛋疼

puzzle9

2020-07-28 17:13:09 +08:00 via Android

记得在知乎看到
注释是
我的代码为何这么做
而不是表达我的代码做了什么

optional

2020-07-28 17:16:41 +08:00 via iPhone

不写注释。

wzzzx

2020-07-28 17:22:57 +08:00

公司的大佬说，注释本质上就是代码的冗余，也是需要维护的。所以要多写一些让人能看懂的代码，就可以不用写注释了

DiamondY

2020-07-28 17:24:30 +08:00

注释为啥是越多越好？我以前看过一些注释啰嗦到像流水账和日记一样，看得贼尴尬

aguesuka

2020-07-28 18:51:30 +08:00

http://www-inf.it-sudparis.eu/cours/java/JAVADOC/writingdoccomments.html

xizismile

2020-07-28 19:48:04 +08:00 via Android

看一看 java 源码中的注释，你就知道哪些地方需要写了

keshawnvan

2020-07-28 21:36:58 +08:00

接口上写，实现上只有代码不能很好解释意图的地方写

no1xsyzy

2020-07-28 23:44:29 +08:00

注释越多越好？

难以阅读的代码提名奖：
在注释中讲个引人入胜的小故事

DreamSpace

2020-07-29 00:08:02 +08:00 via Android

写代码先写 //TODO
代码写完后把"TODO" replace 掉，剩下的就是注释

frankyzf

2020-07-29 00:09:08 +08:00

感觉注释越少越好，如果必须加很多注释可能意味着 code 的逻辑不是很清晰或者需要抽离出方法。整块复杂逻辑除外。

frankyzf

2020-07-29 00:10:09 +08:00

或者命名不够准确

jingsan0801

2020-07-31 14:59:56 +08:00

好几年前公司代码有规范说, 注释不能少于代码量的 30%;
后来才明白好的代码是不需要注释的, 好的代码是能做到自注释的
要写注释的情况是因为代码不能明确说明程序的逻辑, 而且注释应该是对业务逻辑的说明, 而不是代码逻辑.