千万要避免的五种程序注释方式
你是否有过复查程序时发现有些注释毫无用处?程序注释是为了提高代码的可读性,为了让原作者以外的其他开发人员更容易理解这段程序。
我把这些让人郁闷的注释方式归为了五类,同时把写出这些注释的程序员也归为了五类。我希望读了这篇文章后你感觉自己不属于其中的任何一种类型。如果你有兴趣的话可以读一下另外一篇文章 五种程序员(英文),和这篇讲到的五种程序员对比一下。
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(《代码大全》)。
转载于:https://www.cnblogs.com/ifonly/archive/2012/12/03/2799164.html
千万要避免的五种程序注释方式相关推荐
- 程序员要避免的五种程序注释方式
导读:注释,本是提高代码可读性.让其他开发人员更快速地理解程序的,然而一些无意义的注释会让人郁闷至极.本文是国外网站GreaterGeek上的一篇文章,作者通过分类介绍了五种一定要避免的程序注释方式. ...
- 集丰照明|LED五种调光方式详解(DALI/DMX/0-10V/PWM/可控硅)
LED五种调光方式详解 LED的发光原理同传统照明不同,同功率的 LED 光源,因其采用的芯片不同,电流电压参数则不同,故其内部布线结构和电路分布也不同,导致了各生产厂商的光源对调光驱动的要求也不尽相 ...
- 浅谈汽车软件Boot的五种自刷新方式
背景: 汽车软件Boot程序的主要作用是刷新App程序.在在一个具体客户项目中,Boot也是客户需求的一部分,跟随项目也有软件开发计划(有的为了和其它Boot区分,把项目上的Boot称作CB, Cus ...
- 阿里原来是这么干的!Spring Boot 五种热部署方式
作者:若离x 来源:my.oschina.net/ruoli/blog/1590148 1.模板热部署 在 Spring Boot 中,模板引擎的页面默认是开启缓存的,如果修改了页面的内容,则刷新页面 ...
- HTML5 Web 客户端五种离线存储方式汇总
为什么80%的码农都做不了架构师?>>> 最近折腾HTML5游戏需要离线存储功能,便把目前可用的几种HTML5存储方式研究了下,基于HT for Web写了个综合的实例,分别利 ...
- 串口MSComm控件五种不同校验方式对数据收发的影响
(2008-09-10 14:50:00) http://blog.sina.com.cn/s/blog_470eccc60100arq7.html 串口MSComm控件有五种校验方式,分别是 ...
- app启动页html模板,APP引导页设计的五种常见表现方式
app引导页,想必大家都很熟悉.目前来说,APP引导页设计并不是每一个APP的必备设计环节啦.因为一款App是否需要引导页,取决于每一个APP出发点或者说是用途. 比如,在功能引导页和操作引导页上的设 ...
- Java 中Map五种取值方式
map的主要作用是什么? 可以通过创建一个map的实现类 来存放 数据 值 和值的描述 也可以通过描述去取得数据 将键映射到值的对象.一个映射不能包含重复的键:每个键最多只能映射到一个值.此接 ...
- Spring Boot 五种热部署方式,极速开发就是生产力!
欢迎关注方志朋的博客,回复"666"获面试宝典 模板热部署 在 Spring Boot 中,模板引擎的页面默认是开启缓存的,如果修改了页面的内容,则刷新页面是得不到修改后的页面的, ...
最新文章
- php 读取stdclass,json - 在php中读取stdclass的问题?
- PHPStorm IDE 快捷键
- 决策树基本原理与sklearn应用
- 设计模式之(Factory method)工厂方法模式
- 《Java并发编程的艺术》之阻塞队列
- VB.NET工作笔记003---使用ASP_vbs脚本_或vb.net调用Sqlserver DTS文件
- Android应用程序与SurfaceFlinger服务的关系概述和学习计划 .
- 55. mysqli 扩展库(2)
- [python] 解决OSError: Address already in use
- select的使用及缺陷
- 驱动单片机硬件调试器的一些开源库总结(包含stlink调试器)
- php自定义生成用户收据,Shopify POS收据自定义操作步骤
- tcpClient的使用
- 中国K12在线教育用户消费行为报告
- java实验目的_Java实验报告(实验一)
- 用HTML+js实现求圆的面积和周长
- Quadratic Assignment Problem 二次分配问题 QAP
- 小学数学加减法测试软件,儿童数学练习智能出题系统
- [Pycharm] 取消被excluded的文件夹
- 数值分析(一):全选主元高斯消元法的C++实现
热门文章
- Spark提交代码的两种方式
- winapi里的createthread函数 和linux,Windows API---CreateThread函数
- [USACO13NOV]Farmer John has no Large Brown Cow【状压 / 模拟】
- python定时模块:apscheduler
- C++程序调用python3
- bzoj 3527 [Zjoi2014]力——FFT
- FBI为车主支招:如何预防汽车黑客
- PostgreSQL ALTER TABLE中改变数据类型时USING的用法转
- mysql 优化-总结
- Docker实现隔离