关于怎么写好的注释有什么比较好的经验吗？

Question

背景:
目前做一个Java的服务端项目,要求所有Controller,Service,Dao,Entity都需要用标准的Javadoc写注释

@Controller
public class LoginController{
    
    @RequestMapping(value = "/login")
    public void login(String account, String password){
    
    }
    
}

自己觉得对于上面这种方法，一眼就能看出在做什么的，根本不需要写注释，写了注释也是废话

但对于整个项目来说,却需要我们将整个代码写成下面这样

/**
 * 登录相关的业务接口
 * @author xxx
 *
 */
public interface LoginService{
    
    /**
     * 登录
     * @param account 账号
     * @param password 密码  
     * @return 返回用户信息
     * @author xxx   
     */
    User login(String account, String password);
}

如果整个项目都遵循规范也无可厚非。但大多时候，我们只维护了代码，却没有去维护注释，导致注释成了误解

所以很多时候，我都会有一种疑惑，怎么去写恰到好处的注释，不让注释成为显而易见的废话，掩饰了真正的代码意图。能够快速的人知道代码的真正意图

各位有什么好的经验，方法和技巧可以分享吗？

Answer 1

我认为编写注释的话需要团队有一套标准，然后就要靠每个人的自觉的。

Answer 2

我认为，注释不是代码的 再解释，如果说注释很复杂，那么你的代码就很有可能有问题了写 一手好的注释 很像 写简历(个人想法) 我 需要 什么，我目的是什么，我在在 某些场合下 要完成 怎样的事情，什么事情是必须做的，什么是一定不能做的，能过写一手漂亮的注释 我认为比 不会比写一手漂亮的代码简单