千万要避免的五种程序注释方式小结
更新时间：2011年10月28日 15:13:47 作者：
你是否有过复查程序时发现有些注释毫无用处？程序注释是为了提高代码的可读性，为了让原作者以外的其他开发人员更容易理解这段程序。
我把这些让人郁闷的注释方式归为了五类，同时把写出这些注释的程序员也归为了五类。我希望读了这篇文章后你感觉自己不属于其中的任何一种类型。如果你有兴趣的话可以读一下另外一篇文章 五种程序员(英文)，和这篇讲到的五种程序员对比一下。
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
}
}
这种程序员是如此的欣赏自己的程序，以至于不得不在每行代码上都署上自己的大名。应该让版本控制系统来提供程序变更的信息，他这样做一眼看去并不能说明谁对这行代码负责。
2. 过时的程序员
public class Program
{
static void Main(string[] args)
{
/* 这段程序已经不再有用
* 因为我们发现千年虫问题只是一场虚惊
* 我们的系统不会恢复到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)
{
/* 这个程序是用来在屏幕上
* 循环打印1百万次”I Rule!”
* 每次输出一行。循环计数
* 从0开始，每次加1。
* 当计数器等于1百万时，
* 循环就会停止运行*/
for (int i = 0; i < 1000000; i++)
{
Console.WriteLine(“I Rule!”);
}
}
}
基本的编程语法规则我们大家都知道——我们不需要“编程入门”。你不需要浪费时间来解释一个显而易见的东西，我们更希望知道的是你的程序功能——那是浪费空间了。
4. 传奇的程序员
public class Program
{
static void Main(string[] args)
{
/* 有一天我在大街上的一家星巴克里
* 和销售部的Jim讨论问题，他告诉我
* 销售代表是依据以下的比例提取佣金的。
* 周五: 25%
* 周三: 15%
* 其它日期: 5%
* 我是否告诉你过我点了一个卡拉梅
* 铁咖啡和两份的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很可能在公司里不再是销售。而且大多数读到这段注释的程序员未必都知道Jim是谁。你描述的是实际情况但跟我们的内容不相干，所以就省掉吧。
5. 未来程序员
public class Program
{
static void Main(string[] args)
{
//TODO: 将来我会修复这个问题 – 07/24/1995 Bob
/* 我知道这个问题很难解决而且
* 我现在依赖于这个Contains函数，但
* 我以后会用一种更有意义，更
* 优雅的方式打印这段代码。
* 我只是现在没时间。
*/
string message = “An error has occurred”;
if(message.Contains(“error”))
{
throw new Exception(message);
}
}
}
这种注释是一种集大成者，它包含了上面所说的注释的所有问题。TODO注释在一个项目最初的开发阶段是非常有用的，但这个注释看起来是在好几年前的产品程序里的——它证明了程序有问题。如果程序有问题需要解决，马上解决，不要拖到日后再解决。
如果你写过这样的注释，或者是你正在寻找一种最好的注释方案，我推荐你读一读Steve McConnell写的Code Complete这本书。这是我推荐给所有程序员必读的六本书中的一种。或者你可以学学如何停止注释你的程序(英文)。
你是否在你的程序里还见到过其它种没有意义的或讨厌的注释？欢迎共享。
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
}
}
这种程序员是如此的欣赏自己的程序，以至于不得不在每行代码上都署上自己的大名。应该让版本控制系统来提供程序变更的信息，他这样做一眼看去并不能说明谁对这行代码负责。
2. 过时的程序员
复制代码 代码如下:
public class Program
{
static void Main(string[] args)
{
/* 这段程序已经不再有用
* 因为我们发现千年虫问题只是一场虚惊
* 我们的系统不会恢复到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)
{
/* 这个程序是用来在屏幕上
* 循环打印1百万次”I Rule!”
* 每次输出一行。循环计数
* 从0开始，每次加1。
* 当计数器等于1百万时，
* 循环就会停止运行*/
for (int i = 0; i < 1000000; i++)
{
Console.WriteLine(“I Rule!”);
}
}
}
基本的编程语法规则我们大家都知道——我们不需要“编程入门”。你不需要浪费时间来解释一个显而易见的东西，我们更希望知道的是你的程序功能——那是浪费空间了。
4. 传奇的程序员
复制代码 代码如下:
public class Program
{
static void Main(string[] args)
{
/* 有一天我在大街上的一家星巴克里
* 和销售部的Jim讨论问题，他告诉我
* 销售代表是依据以下的比例提取佣金的。
* 周五: 25%
* 周三: 15%
* 其它日期: 5%
* 我是否告诉你过我点了一个卡拉梅
* 铁咖啡和两份的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很可能在公司里不再是销售。而且大多数读到这段注释的程序员未必都知道Jim是谁。你描述的是实际情况但跟我们的内容不相干，所以就省掉吧。
5. 未来程序员
复制代码 代码如下:
public class Program
{
static void Main(string[] args)
{
//TODO: 将来我会修复这个问题 – 07/24/1995 Bob
/* 我知道这个问题很难解决而且
* 我现在依赖于这个Contains函数，但
* 我以后会用一种更有意义，更
* 优雅的方式打印这段代码。
* 我只是现在没时间。
*/
string message = “An error has occurred”;
if(message.Contains(“error”))
{
throw new Exception(message);
}
}
}
这种注释是一种集大成者，它包含了上面所说的注释的所有问题。TODO注释在一个项目最初的开发阶段是非常有用的，但这个注释看起来是在好几年前的产品程序里的——它证明了程序有问题。如果程序有问题需要解决，马上解决，不要拖到日后再解决。
如果你写过这样的注释，或者是你正在寻找一种最好的注释方案，我推荐你读一读Steve McConnell写的Code Complete这本书。这是我推荐给所有程序员必读的六本书中的一种。或者你可以学学如何停止注释你的程序(英文)。
你是否在你的程序里还见到过其它种没有意义的或讨厌的注释？欢迎共享。
相关文章
这篇文章主要介绍了git中ssh key配置详解，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧2020-07-07
今天是大结局，说下“图”的最后一点东西，“最小生成树“和”最短路径“2013-11-11
Visual Studio和Visual Studio Code之间有什么区别
本文给大家介绍的是Visual Studio和Visual Studio Code之间有什么区别,希望对大家的学习能够有所帮助2020-02-02
这篇文章主要介绍了永久解决VSCode终端中文乱码问题，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧2020-08-08
这篇文章主要为大家介绍了BERT vs GPT自然语言处理中的关键差异详解，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪2023-01-01
因为中型公司不可能配置运维开发,而开发只管开发的,所以运维只能是通过使用开源工具的方式来搭建自动化部署系统,下面这篇文章主要给大家介绍了关于Jenkins集成Gitlab实现自动化部署的相关资料,需要的朋友可以参考下2022-04-04
这篇文章主要介绍了如何使用Idea进行合并代码分支,在平时的开发中大多是协作开发的,代码统一放在一起,那么需要代码合并时该怎么操作,需要的朋友可以参考下2023-03-03
在本文中，我们将学习如何在 WordPress 中创建自定义页面模板，以及我们如何将自定义模板分配给 WordPress 中的特定页面或页面组，感兴趣的朋友跟随小编一起看看吧2021-09-09
手把手教你用Hexo+Github搭建属于自己的博客(详细图文)
越来越多的朋友选择自己架设自己的博客，以来方便个性样式二来也能带来不少收入，大部分朋友都会选择wordpress搭建个人博客，这里为大家分享使用Hexo+Github搭建开发者博客的方法,需要的朋友可以参考下2017-10-10
朋友在问如何在IM即时通讯中实现发送图片视频语音和表情呢，今天小编通过本文给大家详细介绍下，感兴趣的朋友一起看看吧2020-05-05
最新评论