V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
Vimax
V2EX  ›  Java

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

  •  1
     
  •   Vimax · 2020-07-28 14:04:50 +08:00 · 3293 次点击
    这是一个创建于 858 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

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

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

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

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

    17 条回复    2020-07-31 14:59:56 +08:00
    TomatoYuyuko
        1
    TomatoYuyuko  
       2020-07-28 14:17:21 +08:00
    有本书叫代码整洁之道
    specita
        2
    specita  
       2020-07-28 15:11:55 +08:00
    注释我不会嫌多的
    sugars
        3
    sugars  
       2020-07-28 15:15:35 +08:00
    注释尽管写,反正前端打包编译时可以移除掉
    pushback
        4
    pushback  
       2020-07-28 15:23:00 +08:00
    @Deprecated 要吧,
    自定义注解要吧,
    method 要吧,
    局部变量要吧,
    内部类要吧,
    yml 要吧,
    iml 要吧,
    qq976739120
        5
    qq976739120  
       2020-07-28 15:27:07 +08:00
    注释多比少好,越多越好,多了我会自己过滤掉多余信息,少了是真的只能硬着头皮看代码,另外,注释和代码不一致更蛋疼
    puzzle9
        6
    puzzle9  
       2020-07-28 17:13:09 +08:00 via Android
    记得在知乎看到
    注释是
    我的代码为何这么做
    而不是表达 我的代码做了什么
    optional
        7
    optional  
       2020-07-28 17:16:41 +08:00 via iPhone
    不写注释。
    wzzzx
        8
    wzzzx  
       2020-07-28 17:22:57 +08:00
    公司的大佬说,注释本质上就是代码的冗余,也是需要维护的。所以要多写一些让人能看懂的代码,就可以不用写注释了
    DiamondY
        9
    DiamondY  
       2020-07-28 17:24:30 +08:00
    注释为啥是越多越好?我以前看过一些注释啰嗦到像流水账和日记一样,看得贼尴尬
    xizismile
        11
    xizismile  
       2020-07-28 19:48:04 +08:00 via Android
    看一看 java 源码中的注释,你就知道哪些地方需要写了
    keshawnvan
        12
    keshawnvan  
       2020-07-28 21:36:58 +08:00
    接口上写,实现上只有代码不能很好解释意图的地方写
    no1xsyzy
        13
    no1xsyzy  
       2020-07-28 23:44:29 +08:00
    注释越多越好?

    难以阅读的代码提名奖:
    在注释中讲个引人入胜的小故事
    DreamSpace
        14
    DreamSpace  
       2020-07-29 00:08:02 +08:00 via Android
    写代码先写 //TODO
    代码写完后把"TODO" replace 掉,剩下的就是注释
    frankyzf
        15
    frankyzf  
       2020-07-29 00:09:08 +08:00
    感觉注释越少越好,如果必须加很多注释可能意味着 code 的逻辑不是很清晰或者需要抽离出方法。整块复杂逻辑除外。
    frankyzf
        16
    frankyzf  
       2020-07-29 00:10:09 +08:00
    或者命名不够准确
    jingsan0801
        17
    jingsan0801  
       2020-07-31 14:59:56 +08:00
    好几年前公司代码有规范说, 注释不能少于代码量的 30%;
    后来才明白好的代码是不需要注释的, 好的代码是能做到自注释的
    要写注释的情况是因为代码不能明确说明程序的逻辑, 而且注释应该是对业务逻辑的说明, 而不是代码逻辑.
    关于   ·   帮助文档   ·   API   ·   FAQ   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   1069 人在线   最高记录 5497   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 50ms · UTC 22:15 · PVG 06:15 · LAX 14:15 · JFK 17:15
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.