您的位置:知识库 » 程序人生

5类应避免使用的代码注释

来源: 译言网  发布时间: 2011-11-19 21:54  阅读: 2314 次  推荐: 0   原文链接   [收藏]  

  英文原文:5 Types of Comments to Avoid Making in Your Code

  你是否曾在检查代码时碰到一条在你看来多余的注释?在代码中使用注释的目的是提升代码的可读性,以让那些非原始代码开发者能更好地理解它们。

  我甄别出5类让我不胜其扰的注释及5类生成它们的程序员。我希望读过本篇之后,你不会与他们一样坠入同一条河流。作为一项挑战,你不妨把写这5类注释的程序员与5类程序员作一下匹配。

  1. 骄傲型程序员(The Proud Programmer)

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. 过时型程序员(The Obsolete Programmer)

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. 显然型程序员(The Obvious Programmer)

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!");
}
}
}

  我们都知道编程的基本工作逻辑,这可不是什么编程入门!你无需浪费时间解释显而易见的程序工作原理,虽然我们很高兴看到你愿意解释代码的功能,但这不过是画蛇添足。

  4. 传记型程序员(The Life Story Programmer)

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 from Sales(译注:销售人员Jim)也许离开这家公司了,那些阅读代码的程序员极可能根本就不知道他是谁,更甭提注释里那些毫无干系的事情。

  5. 总有一天型程序员(The Someday Programmer)

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);
}
}
}

  这类注释在某种程度上说是前面几种类型的大杂烩。TODO注释在项目初始开发阶段用处不小,但是如果几年后出现在产品代码中那就会带来麻烦。如果有什么需要修补的,趁现在动手,而不要推迟到以后去做。

  如果你不幸是生成这些类型注释的人,或者你想学习注释用法的最佳实践,我推荐你阅读Steve McConnell写的Code Complete(《代码大全》)。这是一本我建议程序员必读的书籍。

  或者你也可以彻底点,学习怎样不使用代码注释。

  你是否在自己的代码中看到了其它类型多余或扰人的注释?请不吝分享。

0
1

程序人生热门文章

    程序人生最新文章

      最新新闻

        热门新闻