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

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

• 自恋型注释
  
  下面的代码中，程序员在自己修改的代码处标上了自己的名字，以及完整的日期。
  这是不必要的因为，版本控制工具（如Git）可以记录代码改动者的信息和日期
  不过如果这样的做法团队允许，且程序员觉得这样写比较有意义，倒也是可以。
  1. public class Main {
  2.     public static void main(String[] args) {
  3.         // 1. 自恋型注释
  4.         String message = "Hello, world!"; // 2024-03-01 20:17 云熙橙
  5.         System.out.println(message);  // 2024-03-01 20:17 云熙橙
  7.         message = "我是云熙橙"; // 2024-03-01 20:17 云熙橙
  8.         System.out.println(message);  // 2024-03-01 20:17 云熙橙
  9.     }
  10. }

  复制代码
• 废弃代码注释
  
  下面代码中，一段不会用到的代码被注释了。
  如果某段代码不在使用了，那就应该直接删除，而不是添加大段的注释。
  除非这段代码在后面会用到，但是也要尽量不使用这样的注释。
  1. public class Main {
  2. //    2. 废弃代码注释
  3. //    public void getDetailDate () {
  4. //        Date date = new Date();
  5. //        date.getTime();
  6. //        System.out.println(date);
  7. //    }   
  8. }

  复制代码
• 明显的注释
  
  下面这段代码解释的过于详细，会占用大量的代码空间，影响代码阅读。
  注释应该用来解释代码的设计思路和功能，而不是解释代码本身的逻辑。
  如果代码写得很清楚，根本不需要注释。
  1. public class Main {
  2.     /**
  3.      * 这段代码是一个for循环，循环体中输出当前时间和余额
  4.      * 初始余额为0，每次循环加1，循环100次
  5.      * @param args
  6.      */
  7.     public static void main(String[] args) {
  8.         for (int money = 0; money < 100; money++) {
  9.             System.out.println("当前时间：" + new Date());
  10.             System.out.println("当前余额：" + money);
  11.         }
  12.     }
  13. }

  复制代码
• 故事型注释
  
  下面这段代码标出了联系人，潜台词是不要联系我，请联系下面这个人。
  这种说明应该写在文档中，而不是代码中
  1. public class Main {
  2.     public static void main(String[] args) {
  3.         /**
  4.          * 我其实并不希望你看到这个代码。因为这段代码的逻辑有问题。
  5.          * 我认为不应该这样实现。如果有问题请联系：
  6.          * 联系人: 云熙橙
  7.          * 电话：18888888888
  8.          * 邮箱：34689787@qq.com
  9.          */
  10.         for (int money = 0; money < 100; money++) {
  11.             System.out.println("当前时间：" + new Date());
  12.             System.out.println("当前余额：" + money);
  13.         }
  14.     }
  15. }

  复制代码
• TODO注释
  
  在项目中todo注释非常有用，但是请及时根据todo注释修改代码，而不是将他留下来。
  todo注释不应该出现在发布的代码中。
  1. public class Main {
  2.     public static void main(String[] args) {
  3.     }
  4.     // todo: 添加用户
  5.     public Integer add (Integer a, Integer b) {
  6.         return a + b;
  7.     }
  8. }

  复制代码

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

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！