注释—一把双刃剑
什么是注释,为什么要有注释呢?
在我看来,注释是对代码一个补充.也就是说注释是为了弥补你的代码在表达含义时候的失败.所以我认为除了在必要的情况下,不要写过多的注释.如果你的代码写了过多的注释,是不是应该反思一下自己,自己的代码就这么没有逻辑性吗?干脆推倒重来重构代码,让自己的代码更加具有逻辑性和可读性.
1.不要让自己产生对注释的依赖性
很多程序员在写代码之前并没有考虑到项目的整体架构和逻辑,而是拿起键盘就写.结果写的磕磕绊绊,注释写了一大堆,到了运行的时候发现结果是正确的的.于是便觉得万事大吉.殊不知这是在用注释来掩盖劣质代码恶臭.长此以往,代码规范便被抛之脑后,逻辑能力也大幅下降.所以当你写了一大串的注释的时候应该好好反思一下自己在表达能力上的失败.
糟糕的代码就算加上再好的注释,那也是相当于在厕所里喷香水,治标不治本.
2.什么是糟糕的注释
2.1 能用代码说明的事情为什么要用注释?
//To calculate the area.a is length,b is width
public double fun1(double a,double b)
{
double c=a*b;
return c;
}
上面是一个极端恶臭的例子,大多数人不会真的这么写.但是我相信很多人也会有不同程度的出现这种状况.就是明明能用简明的变量命名,良好的代码逻辑来呈现出来的东西为什么要加上注释!!!.我相信以下代码,大家不用注释也能看懂.
public double calculateRectangleArea(int length,int width)
{
double area=length*width;
return area;
}
2.2说废话
//try and catch the IOExceptiopn
try
{
properties.load(resourceAsStream);
dataSource=DruidDataSourceFactory.createDataSource(properties);
} catch (IOException e)
{
e.printStackTrace();
}
这样的代码是在干嘛?写给不懂coding的普通人看吗?我相信是一个程序员也知道这是在干什么,所以不要浪费你宝贵的时间去做这些无聊的事情.
2.3注释掉的代码
Graphics graphics = bufferedImage.getGraphics();
graphics.setColor(Color.WHITE);
// graphics.setColor(Color.BLUE);
graphics.fillRect(0, 0, length, width);
graphics.setColor(Color.YELLOW);
graphics.drawRect(0, 0, length - 1, width - 1);
很多程序员在写代码的过程会经常的注释掉一些代码,以便进行修改,这是无可厚非的.但是当你已经完成了这段代码,请将哪些注释的代码删除.如果这是一个已经完成的项目,后来的维护者和开发者要怎样对待这些注释的代码?这会给他们带来很多的困扰.
3 什么是必要的代码
3.1 法律和版本信息
有的时候在公司编写代码的时候会要求编写相关的信息放在代码的开头.
3.2阐释和约定
string transCharToString(char ch);
string codeSource;
map<string, int> tokens;//identifier is 1,reservedWord 2,digit 3,borderSymbol 4,operator 5
在编写代码的时候我们方法的返回值或者说某些变量需要通过一种更简单的方式来表达.比如在上述的代码中,map结构中我们约定 1表示标识符,2表示保留字等等,相比于直接使用字符串,这种方式更加简洁.
3.2警告和强调
有的时候代码的可能会产生一些不好的后果,或者某个部分特别重要,这个时候就可以通过注释来告诉后来的维护者和开发者,以免造成严重的后果.
3.3TODO注释
//TODO
@ApiOperation("通过用户id组来删除用户")
@DeleteMapping("/deleteUsers")
public Integer deleteUsers(@RequestBody Map userIds)
{
return null;
}
一个项目的开发往往是漫长的,有些函数或者接口已经定义好了格式,但是还没有完成,就可以在上面加一个TODO来提醒自己将其完成.