CleanCode-注释和格式

海边的飞鹅

于 2022-08-22 23:28:12 发布

阅读量248

点赞数

分类专栏：阅读笔记文章标签： java

本文链接：https://blog.csdn.net/weixin_44831041/article/details/126475615

版权

阅读笔记专栏收录该内容

10 篇文章 0 订阅

订阅专栏

注释

注释的恰当用法是弥补在用代码表达意图时遭遇的失败。

注释会撒谎，注释存在的时间越久，离描述的代码越远，因为成员不能坚持维护注释。
把力气用在写清楚代码上，直接保证无需编写注释。
不准确的注释要比没注释坏的多，真实只在代码中体现，虽然需要注释，但是应该花心思尽量减少注释。

1.注释不能美化糟糕的代码

带有少量注释的整洁而有表达力的代码更好。

2.用代码来阐述

//check to see if the employee is eligible for full benefits
if((employee.flags & HOURLY_FLAG) && emplyee.age > 65) {
    
}

还是

if(employee.isEligibleForFullBenefits()) {
    
}

3.好注释

有些注释是必需的，也是有利的。

（1）法律信息
（2）提供信息的注释

//Returns an instance of the Responder being tested
protected abstract Responder responderInstance();

更好的方式是尽量利用函数名称传达信息，这样注释就是多余了。

protected abstract ResponderBeingTested responderInstance();

再比如，

//format matched kk:mm:ss EEE,MMM dd, yyyy
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\ w*, \\w* \\d*, \\d*)

该正则表达式意在匹配一个经由SimpleDateFormat.format函数利用特定格式字符串格式化的时间和日期。

可以将这段代码转移到某个转换日期和时间格式的类中，会更好、更清晰。

（3）对意图的解释

你也许不同意程序员给这个问题提供的解决方案，但至少知道它要干什么。

（4）阐释

注释把某些晦涩难明的参数或返回值的意义翻译为某种可读形式。适合单行之后//

（5）警示

警告其他程序员会出现某种后果，解释为什么要关闭某个测试用例。
可以结合注释 @Ignore("Takes too long to run")

public static SimpleDateFormat makeStandardHttpDateFormat() {
	// SimpleDateFormat is not thread safe
    // so we need to create each isntance independently;
    SimpleDateFormat df = new SimpleDateFormat("EEE," dd MMM yyyy HH:mm:ss z);
	df.setTimeZone(TimeZone.getTimeZone("GMT"));
	return df;
}

虽然可能有更好的解决方法，不过上面的注释有道理存在，能阻止某位程序员以效率之名使用静态初始器。

（6）TODO注释
解释为什么该函数的实现部分无所作为，将来应该是如何。
认为应该做，但由于某些原因目前还没做。

（7）放大

注释用来重点描述看起来不合理之物的重要性

String listItemcount = match.group(3).trim();
// the trim is real important.It removes the starting spaces that cause the item to be recognized as anoter list

（8）公共API中的Javadoc

良好描述的公共API，标准java库中的Javadoc一般不错。