你是否有过复查程序时发现有些注释毫无用处?程序注释是为了提高代码的可读性,为了让原作者以外的其他开发人员更容易理解这段程序。
我把这些让人郁闷的注释方式归为了五类,同时把写出这些注释的程序员也归为了五类。我希望读了这篇文章后你感觉自己不属于其中的任何一种类型。如果你有兴趣的话可以读一下另外一篇文章五种程序员(英文),和这篇讲到的五种程序员对比一下。
1. 高傲的程序员
- publicclassProgram
- {
-
staticvoidMain(string[]args)
- {
-
stringmessage=“HelloWorld!”;
-
Console.WriteLine(message);
-
message=“Iamsoproudofthiscode!”;
-
Console.WriteLine(message);
- }
- }
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. 过时的程序员
- publicclassProgram
- {
-
staticvoidMain(string[]args)
- {
-
-
-
-
-
-
-
-
- }
- }
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. 天真的程序员
- publicclassProgram
- {
-
staticvoidMain(string[]args)
- {
-
-
for(inti=0;i<1000000;i++)
- {
- Console.WriteLine(“IRule!”);
- }
- }
- }
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. 传奇的程序员
- publicclassProgram
- {
-
staticvoidMain(string[]args)
- {
-
-
doubleprice=5.00;
-
doublecommissionRate;
-
doublecommission;
-
if(DateTime.Today.DayOfWeek==DayOfWeek.Friday)
- {
-
commissionRate=.25;
- }
-
elseif(DateTime.Today.DayOfWeek==DayOfWeek.Wednesday)
- {
-
commissionRate=.15;
- }
-
else
- {
-
commissionRate=.05;
- }
- commission=price*commissionRate;
- }
- }
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. 未来程序员
- publicclassProgram
- {
-
staticvoidMain(string[]args)
- {
-
-
- stringmessage=“Anerrorhasoccurred”;
-
if(message.Contains(“error”))
- {
-
thrownewException(message);
- }
- }
- }
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(《代码大全》)。这是一本我建议程序员必读的书籍,CSDN
地址http://blog.csdn.net/justjavac/article/details/7865418。
你是否在自己的代码中看到了其它类型多余或扰人的注释?请不吝分享。
分享到:
相关推荐
你是否有过复查程序时发现有些注释毫无用处?程序注释是为了提高代码的可读性,为了让原作者以外的其他开发人员更容易理解这段程序。
你是否曾在检查代码时碰到一条在你看来多余的注释?在代码中使用注释的目的是提升代码的可读性,以让那些非原始代码开发者能更好地理解它们。 我甄别出5类让我不胜其扰的注释及5类生成它们的程序员。我希望读过...
本程序是关于对数组,随机数,循环语句的掌握,在做程序之前作出分析,首先建立两个数组红球和蓝球并用for语句遍历赋值,在新建一个数组记录从1-33个球里面随机出来的红球,同时定义一个boolean类型的数组用于比较...
在软件开发的过程中总是强调注释的规范,但是没有一个具体的标准进行说明,通常都是在代码编写规范中简单的描述几句,不能作为一个代码注释检查的标准和依据,做什么都要有一个依据吗:),现在我特整理了一个《Java的...
(2)报告中有实现的关键技术点源代码,源代码书写要有一定的规范,源代码中有相关的注释; (3)作为扩展,有余力的同学,能在界面上能够定时给出可视化展示资源申请过程。 (4)实验结果要附上运行结果的截图,并...
all里面的元素是唯一的,所以,这里要避免函数重名。当然,python对函数的重载也不是很提倡…… 这样在python命令行,可以看见注释了。 比如一个程序是test02.py,先import它,再看 help(test02) 或者在程序中调用...
自己写的多线程进度条,避免主线程窗体假死的功能程序,有详细注释,可直接运行看结果,写给不懂线程知识的人使用的,不用有线程等编程基础,只需添加窗体进自己的程序,然后按照代码注释在对应地方添加自己的函数就...
本书是一本与众不同的程序设计入门教材,实践性以一种特殊的方式被提高到了十分重要的地位,不论对计算机专业的学生,还是非计算机专业的学生,都非常适用。 目前许多程序设计入门教材的主要内容就是详细介绍一门...
matlab程序 本程序基于拉丁超立方对风,光可能出现场景进行模拟及削减 风电、光伏场景不确定性模拟,首先利用正态分布的方法,由一组确定性的方案,生成1000种光伏场景,... 适合初学者进行学习使用程序注释清晰易懂
功能需求描述:采用文字方式分功能模块,阐明系统各功能(注意:要站在方便使用者阅读的角度写,避免使用专业术语,如链表、指针等) 三、总体设计 包括: 总体开发思想:采用的主要数据结构、数据存贮方式、使用的...
此外,本书还讨论了调度的问题,并给出了避免错误和提高性能等问题的有价值的建议。本书使用了大量注释过后 实例来解释实际的概念,并包括Pthreads的简单索引和对标准化的展望。 《POSIX多线程程序设计》适合有经验...
matlab程序 基于正态分布法对风,光可能会出现的场景进行模拟及削减 风电、光伏场景不确定性模拟,首先利用正态分布的方法,由一组确定性的方案,生成1000种光伏场景,为了... 适合初学者进行学习使用程序注释清晰易懂
为了避免浏览器这样做,您应当在注释标签中隐藏脚本。老式的(无法识别 &script> 标签的)浏览器会忽略注释,这样就不会把标签的内容写到页面上,而新式的浏览器则懂得执行这些脚本,即使它们被包围在注释标签中! ...
智慧医疗-基于医疗知识图谱的对话机器人python源码+注释拉满+数据集.zip 【项目资源介绍】 智慧医疗-基于医疗知识图谱的对话机器人python源码+注释拉满+数据集.zip 线上和线下 AI医生,两种模式代码 代码注释拉满、...
该资源详细解读可关注博主免费专栏《论文与完整程序》53号博文 配电网重构是指在满足配电网运行基本约束的前提下,通过改变配电网中一个或多个开关的状态对配电网中一个或多个指标进行优化。通过配电网重构,可以在...
用随机数开发一个洗牌和发牌模拟程序。... 只能使用C/C++语言,源程序要有适当的注释,使程序容易阅读 学生可自动增加新功能模块(视情况可另外加分) 写出课程设计报告,具体要求见相关说明文档
内容概要: 本资源是一份Java分库分表实战案例程序,详细介绍了如何在Java项目中实现分库分表的功能。通过该案例,可以学习到如何将数据库的数据按照一定规则分散到不同...4. 本案例程序仅是一种实现方式,并不代表分库
因为每种调度方案都是一个M 行N 列的矩阵,为了解决智能体的构造问题,本文采用基于精英选择的遗传算法和非支配排序遗传算法求解问题,相比其他群智能优化算法,可以更方便的结合问题。 充电调度模型考虑优化4个性能...
1.请用notepad++等软件编辑主程序文件,参照注释进行相关设置。 2.上传程序到某个目录内,并将此目录设置777权限。 3.浏览器打开主程序文件地址即可。 4.出现“系统错误”可能是文件大小超过NGINX、APACHE或PHP限制...
当数据结构改变时,所有相关的处理过程都要进行相应的修改,每一种相对于老问题的新方法都要带来额外的开销,程序的可重用性差。 由于图形用户界面的应用,程序运行由顺序运行演变为事件驱动,使得软件使用起来...