编写优质代码之五种不当注释

编写优质代码之五种不当注释

1. 自恋型注释

   下面的代码中，程序员在自己修改的代码处标上了自己的名字，以及完整的日期。

   这是不必要的因为，版本控制工具（如Git）可以记录代码改动者的信息和日期

   不过如果这样的做法团队允许，且程序员觉得这样写比较有意义，倒也是可以。

   public class Main {
       public static void main(String[] args) {
           // 1. 自恋型注释
           String message = "Hello, world!"; // 2024-03-01 20:17 云熙橙
           System.out.println(message);  // 2024-03-01 20:17 云熙橙
   
           message = "我是云熙橙"; // 2024-03-01 20:17 云熙橙
           System.out.println(message);  // 2024-03-01 20:17 云熙橙
       }
   }
   

2. 废弃代码注释

   下面代码中，一段不会用到的代码被注释了。

   如果某段代码不在使用了，那就应该直接删除，而不是添加大段的注释。

   除非这段代码在后面会用到，但是也要尽量不使用这样的注释。

   public class Main {
   //    2. 废弃代码注释
   //    public void getDetailDate () {
   //        Date date = new Date();
   //        date.getTime();
   //        System.out.println(date);
   //    }   
   }
   

3. 明显的注释

   下面这段代码解释的过于详细，会占用大量的代码空间，影响代码阅读。

   注释应该用来解释代码的设计思路和功能，而不是解释代码本身的逻辑。

   如果代码写得很清楚，根本不需要注释。

   public class Main {
       /**
        * 这段代码是一个for循环，循环体中输出当前时间和余额
        * 初始余额为0，每次循环加1，循环100次
        * @param args
        */
       public static void main(String[] args) {
           for (int money = 0; money < 100; money++) {
               System.out.println("当前时间：" + new Date());
               System.out.println("当前余额：" + money);
           }
       }
   }
   
   

4. 故事型注释

   下面这段代码标出了联系人，潜台词是不要联系我，请联系下面这个人。

   这种说明应该写在文档中，而不是代码中

   public class Main {
       public static void main(String[] args) {
           /**
            * 我其实并不希望你看到这个代码。因为这段代码的逻辑有问题。
            * 我认为不应该这样实现。如果有问题请联系：
            * 联系人: 云熙橙
            * 电话：18888888888
            * 邮箱：34689787@qq.com
            */
           for (int money = 0; money < 100; money++) {
               System.out.println("当前时间：" + new Date());
               System.out.println("当前余额：" + money);
           }
       }
   }
   

5. TODO注释

   在项目中todo注释非常有用，但是请及时根据todo注释修改代码，而不是将他留下来。

   todo注释不应该出现在发布的代码中。

   public class Main {
       public static void main(String[] args) {
       }
       // todo: 添加用户
       public Integer add (Integer a, Integer b) {
           return a + b;
       }
   }
   

来自陈浩大佬的传奇程序员练级攻略