The elements of java style中文总则-优快云博客

本文链接：https://blog.youkuaiyun.com/iteye_10278/article/details/82233153

本文详细阐述了Java编程中的核心规范与最佳实践，包括代码风格、命名规则、注释编写、异常处理等方面，旨在帮助开发者提高代码质量和可维护性。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

The elements of java style中文总则
通用规约
1.坚持原有代码的规约
   当修改现有代码时，修改应该仍然遵守原来代码的规约.不要试图只修改代码规约来重写原有代码，否则很容易产生错误。
   参见：http://www.gui.com.au/jkoding.htm
2.坚持最少astonishment原则
   应该避免程序产生让用户感到奇怪的行为.应该遵循下面的准则：
     简单：写简单的类和简单的方法.决定做到何种程度就可以满足用户的需求。
     明确：保证每个类、接口、方法、变量和对象都有明确的目的。
     完整：创建完整的文档；对所有的特征和工作做文档。
     一致：风格要一致.相似的东西应该看起来相似，行为相似.尽量创建和应用标准。
     鲁棒性：提供对错误和异常的可预见的处理。
3.立即应用这些规则。
   把这些规则应用到你要写的任何代码中.包括原型开发的代码，等等。
4.对任何偏离规约的变化做文档。
   没有标准是完美的.有时候不得不打破它.首先要理解你要打破的规则的存在理由和后果，其次要为所作的变化做文档。

格式规约
5.缩进被括起来的代码. //关于匿名内置类
6.打破长句子
7.使用空格和空行。
8.不要用tab键。

命名规约
9-14. 用有语义的、大家熟悉的名字. 对过长的名字质疑. 尽量保留名字中的元音字母.对于像XML这样全部大写的缩写，在名字中不必全大写.不要只通过大小写使得两个名字不同。
15-17. 包命名格式：小写；以域名开头.用有意义的名字.不同版本要用新的包名. //这样的话新版本包的命名是个麻烦事。
18-21.类和接口命名。
22-24. 方法命名。
25－31. 变量和常量命名。

注释规约
32.为那些阅读和维护你代码的人写文档。
    那个人很可能就是你自己。
33.注释和代码同步。
34.用准确的语言。
35－37.三种注释的用法。
38.在写代码前写注释。
39.为所有的成员写文档注释。
40.为包写注释。
41.为一个应用或者一组包写注释.注释内容也是写在一个html文件的<body></body>中，也可以使用除@link之外的任何标记.生成文档时用-overview指明这个html文件。
42. 用一种统一的格式做文档注释。
43-45.把关键字、identifiers/constants放在<code></code>中.把源码放在<pre></pre>中.把首次出现的identifier用{@link} 标记，这个标记的作用是生成一个超级链接.例如{@link #Flag(boolean)}是指向本类的一个方法。
46.类、方法、成员变量的文档注释格式。
47.叙述一个类的功能时，尽量不用主语，而谓语采用第三人称单数.常用的动词有：
    adds, deallocates(释放分配的资源）, removes, allocates, destroys, returns, computes, gets, sets, constructs, provides, tests converts, reads, writes，alpplies
48. 写简述.简述放在第一句。
49.一个动作、服务的简述不要写主语。
50.一个东西的简述不要写主语和谓语。
51.指代当前类是用this而不用the.
52.除非特指一个特定的方法，在提到方法名不要带括号。
    意思是说，存在overloaded的方法，如果要泛指同名的方法，就不要带括号，如果特指某一方法，则需要加上括号并列出参数类型。
53.为每个类、接口、成员变量、方法写注释。
54. 为方法做完整的描述。
55.包含例子.在必要时。
56.为方法的前提（例如参数值的限制）、结果（例如类的状态改变）、限制（例如一个叫做vavationDays的变量限制在0－30之间）。
57.为错误和缺陷做注释。
58.为同步语义做注释。
59.只在对别人有帮助时加入内部注释（大概是指方法内部的注释）。
60.描述代码为什么这样做，而不是做什么.代码本身能说明自己在做什么.//这一点保留意见.为什么这样做应该在设计文档或者需求文档中说明了。
61.尽量避免把行末注释放在行末.因为修改这行代码时可能导致一行很长而把注释推到不容易看到的地方。
    把行末注释放在要解释的代码之前，而且另起一行。
62.对变量的注释放在行末。
63.确定一组关键字来说明没有解决的事情.尤其用在代码还没有完成的时候.一般还包括一个时间.例如：
    //:UNRESOLEVED: EBW, 2005-7-20
    这种注释我保留意见.因为关键字说不清楚。
64.对多层嵌套的控制结构，对每个右大括弧做注释.例如 //end if 之类的.如果采用每个大括弧单独成行而且相应括号对齐的话，这种注释就可以取消了。
65.在switch语句中，如果一个case之后没有break语句，则一定要加上一句注释://fall though! 。
66.如果一个控制结构之后的语句块是空的，则请注明 //Empty!.例如
    for (int i=0; i<n; i++);
    //Empty!

编码规约
67.考虑把代表一种数据类型的类声明为final。
68.要使类对nonnative/noconcrete的类依赖最小。
69.定义小的类和小的方法.这写小东西容易设计、编码、测试、注释、读、理解和用.不要提供没有必要的方法。
    实际就是极限编程里的简单设计原则。
70.定义子类时，要使子类在父类可以使用的任何地方都可以使用。
    实际上就是 Liskov替换原则：Methods that use references to base classes must be able to use objects of derived classes without knowing it。
    如果要override父类的方法或变量，请不要让使用此子类的客户端感觉到行为有什么不同。
    如果很好的坚持了这样一个原则，说明设计者对问题域做了很好的抽象。
    开闭原则：Software entities(Classes, Modules, Mothods and so on) should be open for extension, but closed for modification。
71.所有field声明为private。
72. 不用instanceof，而用多态性。
    意思是说，把特定对象的行为实现在从基类继承来的方法中。
73.一些类型（如List等等）对Object类型的对象操作，如果返回的是Object类型的对象，将其强制转换成特定类型。
74.以类实现枚举类型。
75.一段代码只出现一次.把重复的代码重写成一个方法或类。
76.在控制语句中采用语句块。
    语句块可以放在一个语句可以放的任何地方(但是必须放在一个类或者接口的内部）。
77.用括号来明确计算顺序。
78.在每个case后加一个break；
79.使用equals方法，而不是用"=="来比较两个对象是否相同。
    注意："bob".equals(name); 中，如果name是null并不报错。
80.创建一个具有有效状态的对象。
    意思是说，不要创建一个没有初始化的对象。
81.不要在构造方法内部调用非final方法。
    因为子类可能会override一个非final的方法.java会先调用子类中符合的方法。
82.写一个构造方法时使用已有的构造方法来减少代码。
83.不必catch run-time异常.因为这样的异常常常会导致程序停止。
84.要catch会在正常条件下可能发生的异常。
85.使用return来报告状态改变.//没看懂。
86.保持所有的异常信息。
87.对catch的异常要打印相关信息。
88.用finally语句块来释放资源.即使抛出了异常，finally语句块中的代码也会被执行。
89.Program by contract。
    把每个方法看成一个合同.调用一个方法时，要满足它的前提。
    用断言来确保每个方法的前提和结果。
    override同步方法时不能继承方法的同步关键字.可以在父类用一个同步的final方法调用一个非final的方法.那个非final的方法就可以被override了。
90.用dead code elimination实现断言.//不懂。
91. 用断言捕获代码中的逻辑错误。
92.用断言测试一个方法的前提和后果。
93.只有在必要时才使用多线程。
94.尽量不要使用同步。
100.Use lazy initialization