Java学习笔记(六)——google java编程风格指南(下)
2014-02-11 15:34
225 查看
【前面的话】
年后开始正式上班,计划着想做很多事情,但是总会有这样那样的打扰,不知道是自己要求太高还是自我的奋斗意识不够?接下来好好加油。好好学学技术,好好学习英语,好好学习做点自己喜欢的事情,趁着自己还是一个人。
如果你想要学习关于编码风格方面的知识,建议直接阅读参考资料中的文章,比看我这里写的好多了,这是真心话,我只是写自己的笔记。便于自己在以后的编码中注意。
【问题背景】
在做开发工作的时候,总是被说编码风格不好,现在自己找了Google Java编程风格指南进行学习,希望可以写出清晰的代码。
[b]【学习资料】[/b]
1. Google Java编程风格指南,作者:Hawstein
http://hawstein.com/posts/google-java-style.html
【知识汇总】
十二、编程实践
1.@Override:能用则用
只要是合法的,就把
2.捕获的异常:不能忽视
对于捕获的异常,大多数都要做响应。
例外:一个捕获的异常被命名为
如果它确实是不需要在catch块中做任何响应,需要做注释加以说明(如下面的例子)。
3.静态成员:使用类进行调用
使用类名调用静态的类成员,而不是具体某个对象或表达式。
4.Finalizers: 禁用
十三、Javadoc
1.格式
一般形式:
这样:
或这样:
段落
空行(即,只包含最左侧星号的行)会出现在段落之间和Javadoc标记(@XXX)之前(如果有的话)。除了第一个段落,每个段落第一个单词前都有标签
Javadoc标记
标准的Javadoc标记按以下顺序出现:
2.摘要片段
每个类或成员的Javadoc以一个简短的摘要片段开始。这个片段是非常重要的,在某些情况下,它是唯一出现的文本,比如在类和方法索引中。
这只是一个小片段,可以是一个名词短语或动词短语,但不是一个完整的句子。它不会以A {@code Foo} is a...或This method returns...开头, 它也不会是一个完整的祈使句,如Save the record...。然而,由于开头大写及被加了标点,它看起来就像是个完整的句子。
Tip:一个常见的错误是把简单的Javadoc写成
3. 哪里需要使用Javadoc
至少在每个public类及它的每个public和protected成员处使用Javadoc。
例外:
不言自明的方法
对于简单明显的方法如getFoo,Javadoc是可选的(即,是可以不写的)。这种情况下除了 写“Returns the foo”,确实也没有什么值得写了。
单元测试类中的测试方法可能是不言自明的最常见例子了,我们通常可以从这些方法的描述性命名中知道它是干什么的,因此不需要额外的文档说明。
重载
如果一个方法重载了超类中的方法,那么Javadoc并非必需的。
可选的Javadoc
对于包外不可见的类和方法,如有需要,也是要使用Javadoc的。如果一个注释是用来定义一个类,方法,字段的整体目的或行为,那么这个注释应该写成Javadoc,这样更统一更友好。
编程风格完。。。。。。
【后面的话】
简单的生活,简单的过,努力奋斗。我生活的舒适日子要到头了,明天开始自主开发项目,加油吧,少年。
——TT
年后开始正式上班,计划着想做很多事情,但是总会有这样那样的打扰,不知道是自己要求太高还是自我的奋斗意识不够?接下来好好加油。好好学学技术,好好学习英语,好好学习做点自己喜欢的事情,趁着自己还是一个人。
如果你想要学习关于编码风格方面的知识,建议直接阅读参考资料中的文章,比看我这里写的好多了,这是真心话,我只是写自己的笔记。便于自己在以后的编码中注意。
【问题背景】
在做开发工作的时候,总是被说编码风格不好,现在自己找了Google Java编程风格指南进行学习,希望可以写出清晰的代码。
[b]【学习资料】[/b]
1. Google Java编程风格指南,作者:Hawstein
http://hawstein.com/posts/google-java-style.html
【知识汇总】
十二、编程实践
1.@Override:能用则用
只要是合法的,就把
@Override注解给用上。
2.捕获的异常:不能忽视
对于捕获的异常,大多数都要做响应。
例外:一个捕获的异常被命名为
expected,则它可以被不加注释地忽略
try { emptyStack.pop(); fail(); } catch (NoSuchElementException expected) { }
如果它确实是不需要在catch块中做任何响应,需要做注释加以说明(如下面的例子)。
try { int i = Integer.parseInt(response); return handleNumericResponse(i); } catch (NumberFormatException ok) { // it's not numeric; that's fine, just continue } return handleTextResponse(response);
3.静态成员:使用类进行调用
使用类名调用静态的类成员,而不是具体某个对象或表达式。
Foo aFoo = ...; Foo.aStaticMethod(); // good aFoo.aStaticMethod(); // bad somethingThatYieldsAFoo().aStaticMethod(); // very bad
4.Finalizers: 禁用
十三、Javadoc
1.格式
一般形式:
这样:
/** * Multiple lines of Javadoc text are written here, * wrapped normally... */ public int method(String p1) { ... }
或这样:
/** An especially short bit of Javadoc. */
段落
空行(即,只包含最左侧星号的行)会出现在段落之间和Javadoc标记(@XXX)之前(如果有的话)。除了第一个段落,每个段落第一个单词前都有标签
<p>,并且它和第一个单词间没有空格。
Javadoc标记
标准的Javadoc标记按以下顺序出现:
@param,
@return,
@throws,
@deprecated, 前面这4种标记如果出现,描述都不能为空。当描述无法在一行中容纳,连续行需要至少再缩进4个空格。
2.摘要片段
每个类或成员的Javadoc以一个简短的摘要片段开始。这个片段是非常重要的,在某些情况下,它是唯一出现的文本,比如在类和方法索引中。
这只是一个小片段,可以是一个名词短语或动词短语,但不是一个完整的句子。它不会以A {@code Foo} is a...或This method returns...开头, 它也不会是一个完整的祈使句,如Save the record...。然而,由于开头大写及被加了标点,它看起来就像是个完整的句子。
Tip:一个常见的错误是把简单的Javadoc写成
/** @return the customer ID */,这是不正确的。它应该写成
/** Returns the customer ID. */。
3. 哪里需要使用Javadoc
至少在每个public类及它的每个public和protected成员处使用Javadoc。
例外:
不言自明的方法
对于简单明显的方法如getFoo,Javadoc是可选的(即,是可以不写的)。这种情况下除了 写“Returns the foo”,确实也没有什么值得写了。
单元测试类中的测试方法可能是不言自明的最常见例子了,我们通常可以从这些方法的描述性命名中知道它是干什么的,因此不需要额外的文档说明。
重载
如果一个方法重载了超类中的方法,那么Javadoc并非必需的。
可选的Javadoc
对于包外不可见的类和方法,如有需要,也是要使用Javadoc的。如果一个注释是用来定义一个类,方法,字段的整体目的或行为,那么这个注释应该写成Javadoc,这样更统一更友好。
编程风格完。。。。。。
【后面的话】
简单的生活,简单的过,努力奋斗。我生活的舒适日子要到头了,明天开始自主开发项目,加油吧,少年。
——TT
相关文章推荐
- Java学习笔记(四)——google java编程风格指南(上)
- 东软老师上课笔记 2014.11.14 Java学习指南
- Netty权威指南 第2版学习笔记1——Java的I/O演进之路
- Google App Engine for java学习笔记
- Java学习指南学习笔记
- Java学习笔记(五)——google java编程风格指南(中)
- Java8学习笔记(九)--日期/时间(Date Time)API指南
- java学习笔记4_Eclipse使用指南和.classpath,.project, /src和/bin
- Redis学习笔记-java-Jedis链接(一)
- 学习笔记7—Java基础5_多线程
- java学习笔记一:类的执行过程
- java动态代理学习笔记
- 【JAVA学习】EffectiveJava的学习笔记--第二章 Object类的通用方法
- JAVA学习笔记(1)
- Java学习笔记002——类、对象、封装
- 类字符串java学习笔记06--正则表达式
- JAVA学习笔记(五十)- JDBC Java数据库连接
- 【知了堂学习笔记】Java中static关键字的一些简单使用方法
- iphone编程指南学习笔记1
- Java学习笔记(一)