程序员应该避免的 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);
       }
    }
}

这种类型的注释包含了上面所有其他类型。如果是在项目的初始开发阶段,这种待做注释是非常有用的,但如果是在几年后的产品代码——那就会出问题了。如果有什么需要修复的,立马解决,不要把它搁置一边,“以后再做”。

如果你也常常犯这样的注释错误,如果你想了解注释的最佳做法,我建议你阅读类似于Steve McConnell写的《Code Complete》这样的好书。

原文发布于微信公众号 - 瞎说开发那些事(jsj201501)

原文发表时间:2015-11-08

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏游戏开发那些事

【Unity游戏开发】Lua中的os.date和os.time函数

  最近马三在工作中经常使用到了lua 中的 os.date( ) 和 os.time( )函数,不过使用的时候都是不得其解,一般都是看项目里面怎么用,然后我就...

1794
来自专栏JavaEdge

放弃 Calender优雅地使用Joda-Time吧Joda 大型项目Joda 简介Joda 和 JDK 互操作性Joda 的关键日期/时间概念

2987
来自专栏撸码那些事

最佳编码实践——单一职责原则

同时应用这些最佳实践,可以提升代码适应变更的能力。但是凡事要有度,过度使用虽然可以让代码有很高的自适应能力,但是会导致层次粒度过小而难以理解或使用,还会影响代码...

1316
来自专栏Java学习网

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

程序员应该避免的5种代码注释 你有没有这样的经历:别人审查过你的代码之后给出的注释,你认为是没有必要的?注释代码是为了提高代码的可读性,目的是为了能让其他人更容...

2498
来自专栏NetCore

[原创]Fluent NHibernate之旅(四)-- 关系(下)

最近一直忙着准备去旅行的东东,所以进度慢下来了,明天就要出发了,嘿嘿,在出发前,把多对多给写完吧。如果你第一次看这个系列,可以先看看先前几篇,了解下。 一、开篇...

21310
来自专栏阿炬.NET

【人在江湖飘,哪有不带刀】神器Jumony

4016
来自专栏Java成神之路

Java企业微信开发_Exception_01_"errcode":60011,"errmsg":"no privilege to access/modify contact/party/agent

1.组装json数据时,有些字段的值是不能包含双引号的,比如department。所以就没有用JSONObject.fromObject方法了,直接用字符串按照...

1313
来自专栏一枝花算不算浪漫

[Java]Java日期及时间库插件 -- Joda Time.

42611
来自专栏喔家ArchiSelf

老曹眼中的Lambda世界

“ λ ”像一个双手插兜儿,独自行走的人,有“失意、无奈、孤独”的感觉。λ 读作Lambda,是物理上的波长符号,放射学的衰变常数,线性代数中的特征值……在程序...

1112
来自专栏dotnet & java

WCF入门(6)

昨天早上去医院做入职体检,被告知要预约,本以为是要排队,我连视频都准备好了。。。结果就回来了。下午去了新公司那边找房子,2了,因为公司提供了班车列表,我既然就只...

912

扫码关注云+社区

领取腾讯云代金券