程序员应该避免的5种代码注释

最新推荐文章于 2024-07-18 15:08:42 发布

原创最新推荐文章于 2024-07-18 15:08:42 发布 · 676 阅读

0 ·

CC 4.0 BY-SA版权

Linux C 专栏收录该内容

383 篇文章

订阅专栏

本文探讨了程序员在代码注释中常见的五种无效类型，并提供了避免它们的建议，旨在提高代码可读性和团队合作效率。

程序员应该避免的5种代码注释

你有没有这样的经历：别人审查过你的代码之后给出的注释，你认为是没有必要的？注释代码是为了提高代码的可读性，目的是为了能让其他人更容易理解你的代码。

我特别讨厌这5种注释类型以及制造它们的程序员。希望你不是其中之一。

1.自以为很了不得的程序员

public class Program

{

    static void Main(string[] args)

    {

        string message = "Hello World!"; // 07/24/2010 Bob

        Console.WriteLine(message); // 07/24/2010 Bob

        message = "I am so proud of this code!"; // 07/24/2010 Bob

        Console.WriteLine(message); // 07/24/2010 Bob

    }

}

这个程序员自认为写了一段很了不得的代码，所以觉得有必要用自己的名字对每行代码进行标记。实施版本控制系统（VCS）能实现对代码变更的问责，但是也不会这么明显知道谁应对此负责。

2.过时的程序员

public class Program

{

    static void Main(string[] args)

    {

        /* This block of code is no longer needed

         * because we found out that Y2K was a hoax

         * and our systems did not roll over to 1/1/1900 */

        //DateTime today = DateTime.Today;

        //if (today == new DateTime(1900, 1, 1))

        //{

        //    today = today.AddYears(100);

        //    string message = "The date has been fixed for Y2K.";

        //    Console.WriteLine(message);

        //}

    }

}

如果一段代码已不再使用（即过时），那就删除它——不要浪费时间给这些代码写注释。此外，如果你需要复制这段被删除的代码，别忘了还有版本控制系统，你完全可以从早期的版本中恢复代码。

3.多此一举的程序员

public class Program

{

    static void Main(string[] args)

    {

        /* This is a for loop that prints the

         * words "I Rule!" to the console screen

         * 1 million times, each on its own line. It

         * accomplishes this by starting at 0 and

         * incrementing by 1. If the value of the

         * counter equals 1 million the for loop

         * stops executing.*/

        for (int i = 0; i < 1000000; i++)

        {

            Console.WriteLine("I Rule!");

        }

    }

}

我们都知道基础的编程逻辑是如何工作的——所以你不需要多此一举来解释这些显而易见的工作原理，虽然说你解释得很happy，但这只是在浪费时间和空间。

4.爱讲故事的程序员

public class Program

{

    static void Main(string[] args)

{

       /* I discussed with Jim from Sales over coffee

        * at the Starbucks on main street one day and he

        * told me that Sales Reps receive commission

        * based upon the following structure.

        * Friday: 25%

        * Wednesday: 15%

        * All Other Days: 5%

        * Did I mention that I ordered the Caramel Latte with

        * a double shot of Espresso?

       */

        double price = 5.00;

        double commissionRate;

        double commission;

        if (DateTime.Today.DayOfWeek == DayOfWeek.Friday)

        {

            commissionRate = .25;

        }

        else if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday)

        {

            commissionRate = .15;

        }

        else

        {

            commissionRate = .05;

        }

        commission = price * commissionRate;

    }

}

如果你一定要在注释里提及需求，那么不要涉及别人的名字。销售部门的Jim可能会离开公司，而且很有可能大多数程序员根本不知道这是何许人也。不要在注释里提及不相干的事实。

5.“以后再做”的程序员

public class Program

{

    static void Main(string[] args)

    {

       //TODO: I need to fix this someday - 07/24/1995 Bob

       /* I know this error message is hard coded and

        * I am relying on a Contains function, but

        * someday I will make this code print a

        * meaningful error message and exit gracefully.

        * I just don't have the time right now.

       */

       string message = "An error has occurred";

       if(message.Contains("error"))

       {

           throw new Exception(message);

       }

    }

}