Java Coding Style Guide
软件的规模、年龄和复杂性都在增长. Programmers now spend more time reading, maintaining, 改进代码，而不是编写原始代码. Therefore, 专业程序员不仅要能够编写高效和正确的代码，这一点至关重要, 但它也必须用别人能理解的风格来写.
组织使用编码标准来帮助每个人更可靠地一起工作, improve quality, reduce development time, and allow quicker maintenance. 在编写代码时，你的指导原则应该是读者是否容易理解你的意思和代码的作用. 设计良好、编写良好的代码是调试、维护和增强的乐趣.
We will use a subset of Sun Microsystem’s Java Coding Conventions. 您应该在为本课程开发的所有源代码中遵循这些约定. Refer to How To Write Javadoc Comments for tips on the appropriate use of Javadoc tags.
Code Layout
源代码的一致布局不仅提高了可读性，而且提供了专业的外观.
- Use four spaces for indentation. 将编辑器设置为自动将制表符扩展为4个空格
- Avoid lines longer than 72 characters.
- 通过在逗号和操作符后面放置回车符，将长度超过72个字符的语句分成多行.
- 打印的源代码不应该有换行行.
- 缩进复合语句，如循环和分支语句. See example below.
- 像对switch语句那样缩进嵌套的if语句. See example below.
- 将开始大括号“{”与类头放在同一行, method header, conditional statement (if, switch), and loops.
- 将闭括号'}'缩进到与相应类头相同的级别, method header, conditional statement, and loops.
Comments
- 注释应该用于给出代码的概述，并提供代码本身不容易获得的附加信息. 注释应该只包含与阅读和理解程序相关的信息. 避免重复代码中明显的信息.
- Javadoc注释必须以/**开头，以*/结尾
Class Headers
所有源文件都应该以列出类名的类头开始, version information, and author. 在适当的地方使用Javadoc@author和@version标签. See sample code below.
Method Headers
为包含水平线的每个方法提供标题，使标题在视觉上与众不同. Use two blanks lines before each method header. 在适当的地方使用Javadoc @param、@return和@throws标记. See sample code below.
Block Comments
单行注释出现在循环和分支语句等“有趣的事件”之前. 在注释之前提供一个空行，并用它所描述的代码缩进. See sample code below.
如果使用的话，行尾的注释应该整齐地放在72个字符的行中.
Declarations
- 每行提供一个变量声明，并在每个声明之前提供javadoc注释. See sample below.
- 只在块的开头放置声明. 该规则的一个例外是for循环中的索引.
- 在类定义的顶部声明实例变量(不实例化对象).
- 在类构造函数中实例化实例变量(不要声明它).
- 在方法开始时声明和初始化局部变量.
Statements
- Each line should contain only one statement.
White Space
空行通过分隔逻辑相关的代码部分来提高可读性.
- Use a blank line before each method header.
- Use a blank line before each comment.
- 在方法中声明的局部变量与其第一条语句之间使用空行.
- Use a blank space around operators.
Naming Conventions
命名约定使程序更易于阅读，从而使程序更易于理解.
- 类名应该是名词，并以大写字母开头. Keep the name simple and descriptive.
- 方法名应该是动词，并以小写字母开头.
- Variable names should be short yet meaningful. 除了循环变量外，避免使用单个字符的名称.
- 定义为final或打算用作常量的变量应该使用全大写.
Programming Principles
以下建议有助于防止常见错误并加强强大的软件设计原则.
- 如果没有充分的理由，请避免将实例或类变量设为公共变量.
- 对作为对象状态一部分的数据使用实例变量.
- 如果数据不是对象状态的一部分，则在方法中使用局部变量.
- 尽量在方法的末尾使用一个返回语句. 但是，可以有合理的异常来提高可读性或效率.
- 避免在循环和if语句中使用break语句. 但是，可以有合理的异常来提高可读性或效率.
- 尽量保持方法简短，只执行一个任务(少于20行). This is a software engineering principle called high cohesion.
- Avoid numeric constants. 相反，在块的顶部定义一个命名常量. For example,
final int MONTHS = 12;
- 错误消息和输出应该清晰一致.
- 图形用户界面(GUI)应该具有专业的外观.
Sample Source Code (with JavaDoc comments)
JavaDoc注释只在类定义之前提供, methods, and instance variable declarations. 传统的Java注释应该根据需要在方法体中使用.
/*****************************************************************
图形表示的六面模具与各种控制的外观. Current value is constrained between 1 and 6.
@author Joanne Programmer
@version Winter 2007
*****************************************************************/
public class Dice extends Panel {
/** current value of the die */
private int myValue;
/** current size in pixels */
private int mySize;
/** number of miliseconds between rolls */
private int myDelay;
/** color of the dots */
private Color myColor;
/** background color */
private Color myBackground;
/*****************************************************************
构造函数创建一个指定大小X大小像素的die
@param size the length of each side in pixels
*****************************************************************/
public Dice(int size) {
//初始化模具并确定显示特性
mySize = size;
dotSize = mySize / 5;
setBackground(Color.white);
myColor = new Color(0,0,0);
myColor = Color.black;
setLayout(null);
myValue = (int) (Math.random()*6)+1;
}
/*****************************************************************
默认构造函数创建一个大小为100 X 100像素的die
*****************************************************************/
public Dice( ) {
this(100);
}
/*****************************************************************
设置动画帧之间的延迟(以毫秒为单位). Default value is 250.
@param msec milliseconds to delay
*****************************************************************/
public void setDelay (int msec) {
myDelay = 0;
if (msec > 0)
myDelay = msec;
}
/*****************************************************************
Display the current value of the die. Called automatically after rolling. There is no need to call this method directly.
@param g the graphics context for the panel
@return none
*****************************************************************/
public void paintComponent(Graphics g) {
//ask my parent to paint needed components super.paintComponent(g);
// paint dots based on current value
switch (myValue) {
case 1:
g.fillOval (middle, middle, dotSize, dot);
break;
case 2:
g.fillOval (left, left, dotSize, dotSize);
g.fillOval (right, right, dotSize, dotSize);
break;
case 3:
g.fillOval (middle, left, dotSize, dotSize);
g.fillOval (middle, middle, dotSize, dotSize);
g.fillOval (middle, right, dotSize, dotSize);
break;
case 5:
g.fillOval (middle, middle, dotSize, dotSize);
// the "break" statement is intentionally omitted here
// fall through and paint four more dots
case 4:
g.fillOval (left, left, dotSize, dotSize);
g.fillOval (left, right, dotSize, dotSize);
g.fillOval (right, left, dotSize, dotSize);
g.fillOval (right, right, dotSize, dotSize);
break;
case 6:
g.fillOval (left, left, dotSize, dotSize);
g.fillOval (left, middle, dotSize, dotSize);
g.fillOval (left, right, dotSize, dotSize);
g.fillOval (right, left, dotSize, dotSize);
g.fillOval (right, middle, dotSize, dotSize);
g.fillOval (right, right, dotSize, dotSize);
break;
}
}
}
Additional References
- Sun Microsystem’s Java Coding Conventions
- How To Write Javadoc Comments
- J. Langr, Essential Java Style, Prentice Hall, 2000
- A. Vermeulen et al., The Elements of Java Style, Cambridge University Press, 2000.