Name Java Language Code Specification (Java Code Conventions)
Translator Morning (MORNING)
Introduction This document tells the code specification of the Java language, compared with the "Mr. Chen Shizhong" C Code Specification ", this article is a short-sighted. The terms listed in the terms, from coding style, to precautions, not only Java, for other languages, are also known for other languages. Because of a short, it is easy to book, everyone may wish to use this as a Handbook, a standing case, an eye-on.
Declaration requires copying, dissemination, please attach this statement, thank you.
Original article: http://java.sun.com/docs/codeconv/html/codeconvtoc.doc.html,
Translation Source: http://morningspace.51.net/ ,moyingzz@etang.com
table of Contents
1 Introduction 1.1 Why is there a code specification 1.2 Copyright Notice 2 File Name 2.1 File suffix 2.2 Common file name 3 file organization 3.1 Java Source File 3.1.1 Opening Note 3.1.2 Package and Introduction Statement 3.1.3 and Interface Declaration 4 indentation Tsetting 4.1 Row Level 4.2 Renewal 5 Notes 5.1.1.1 Intermuntered Format 5.1.2 Note 5.1.3 Listing Note 5.1.4 Row Note 5.2 Word Net Notes 6 Declaration 6.1 The number of declared variables per line 6.3 Initialization 6.3 Layout 6.4 and interface declaration 7 statement 7.1 Simply statement 7.2 Composite statement 7.3 Return Statement 7.4 IF, IF-ELSE, IF ELSE-IF ELSE Statement 7.5 for Statement 7.6 While Statement 7.7 Do-While Statement 7.8 Switch Statement 7.9 Try-Catch Statement 8 Blank 8.1 Empty Route 8.2 Space 9 Naming Specification 10 Programming Practice 10.1 Provides access control of an example and class variables 10.2 Reference class variable and class method 10.3 Constant 10.4 variable assignment 10.5 Other practical 10.5.1 Parentheses 10.5.2 Return Value 10.5. 3 Conditional operators "?" The expression "?" Before the expression 10.5.4 Special Note 11 Code Example 11.1 Java Source File Example
1 Introduction
1.1 Why have the code specification (Why Have Code Conventions)
The coding specification is especially important for programmers, and there are several reasons:
- A software life cycle, 80% of the cost is maintenance
- There is almost no software, which is maintained by the initial developers in the entire life cycle.
- The coding specification can improve the readability of the software, allowing programmers to completely understand new code as soon as possible.
- If you release the source code as a product, you need to make it very well packaged and clear, as you have built any other product
In order to implement specifications, each software developer must consistently comply with the coding specification. everyone.
1.2 Copyright Notice (ACKNOWLEDGMENTS)
This document reflects the coding standard part of Sun Microsystems, Java language norms. The main contributors include: Peter King, Patrick Naughton, Mike Demoney, Jonni Kanerva, Kathy Walrath, and Scott Hommel.
This document is now maintained by Scott Hommel, please send it to Shommel@eng.sun.com for comments.
2 file name (File names)
This part lists the commonly used file names and their suffixes.
2.1 File suffixes (File Suffixes)
Java program uses the following file suffix: file category file suffix
Java source file .java
Java byte code file .class
2.2 Common file names (Common file names)
Common file names include:
File name use
The preferred file name of Gnumakefile makefiles. We use Gnumake to create a (Build) software.
ReadMe Overview of the preferred file name of the file included in the specific directory
3 file organization (File ORGANIZATION)
A file is constructed by a paragraph divided by a space, and an optional annotation that identifies each paragraph. More than 2,000 rows of procedures are difficult to read and should be avoided as much as possible. "Java Source File Example" provides a reasonable Java program example.
3.1 Java Source File (Java Source Files)
Each Java source file contains a single public class or interface. If private and interfaces are associated with a public class, they can put them and public classes in the same source file. The public category must be the first class or interface in this file.
The Java source file also follows the following rules:
- Start comments (see "Opening Notes")
- Bag and introduction statement (see "Package and introduction statement")
- Class and Interface Declaration (see "Class and Interface Declaration")
3.1.1 BEGINNING Comments
All source files should be at the beginning with a C language style annotation, where the class name, version information, date, and copyright statement are listed:
/ *
* ClassName
*
* Version Information
*
* Date
*
* CopyRight Notice
* /
3.1.2 Packages and introduction statements (Package and Import Statements)
In most Java source files, the first non-promised line is a packet statement. You can follow the introduction statement after it. E.g:
Package java.aw;
Import java.awt.peer.canvaspeer;
3.1.3 Class and Interface Declaration (Class and Interface Declarations)
The following table describes the various parts of the class and interface declarations and the order of them appear. See "Java Source File Example" An example of a comment.
Partial / interface declaration
1 Class / Interface Document Note (/ ** ... * /) See "Document Notes" in this comment
Category 2 or interface
Class 3 / Interface Implementation (/ * ... * /) If necessary, the comment should contain any information about the entire class or interface, and this information is not suitable as a class / interface document comment.
The 4 types of (static) variables are firstcoming the common variables of the class, followed by the protection variable, and then the package level variable (no access modifier, access modifier), and finally the private variable.
5 instance variables are first common, followed by the protection level, and then the package level (no access to the modifier), and finally the private level.
6 constructor
7 Methods These methods should be packetized by function, rather than scope or access. For example, a private class method can be placed between two public instance methods. Its purpose is to make it easier to read and understand the code.
4 indentation typesetting (Indentation)
4 spaces are often used as a unit of indentation. The exact interpretation of indentation is not specified in detail (space VS. Table). A tab is equal to 8 spacers (rather than 4).
4.1 Line Length
Try to avoid a row of more than 80 characters, because many terminals and tools cannot be well processed.
Note: The examples used in the document should use a shorter chance, and the length is generally not more than 70 characters.
4.2 Wrapping Lines
When an expression cannot accommodate in one line, it can be disconnected according to the following general rules: - Disconnected in a comma
- Disconnected in front of one operator
- Ningcomby Higher-Level is selected, not a lower level (Lower-Level)
- New line should be aligned with the beginning of the same level of expression
- If the above rules have caused your code to confuse or make your code piles in the right, then it is to indent 8 spaces.
The following is some examples of disconnect calls:
SomeMethod (LONGEXPRESSION1, LONGEXPIESSION2, LONGEXPRESSION3,
LONGEXPIPRESSION4, LONGEXPRESSION5);
Var = SomeMethod1 (LONGEXPRESSION1,
SomeMethod2 (LONGEXPRESSION2,
LONGEXPIESSION3)))
The following is an example of two breakdown spell expressions. The former is better because the disconnect is located outside the bracket expression, which is a higher level of disconnection.
Longname1 = longname2 * (longname3 longname4 - longname5)
4 * longname6; // preffer
Longname1 = longname2 * (longname3 longname4
- longname5) 4 * longname6; // Avoid
The following is an example of two indentation methods declared. The former is a conventional situation. If the latter uses a regular indentation method, it will move the second line and the third row very right, so the generation is to indent the 8 space.
// conventional indentation
SomeMethod (int Anarg, Object Anothererarg, String Yetanotherarg,
Object andstillanother {
...
}
// Indent 8 spaces to avoid very deep indents
Private static synchronized horkinglongmethodname (int Anarg,
Object Anotherarg, String Yetanothererarg,
Object andstillanother {
...
}
The wrap of the IF statement usually uses 8 space rules, because conventional indentation (4 spaces) will make the statement look more difficult. such as:
// don't use this indentation
IF (Condition1 && Condition2)
|| (Condition3 && Condition4)
||! (Condition5 && condition6)) {// bad wraps
DOSMETHINGABOUTIT (); // make this line easy to miss
}
// use this indeetation instead
IF (Condition1 && Condition2)
|| (Condition3 && Condition4)
||! (Condition5 && condition6)) {
DOSMETHINGABOUTIT ();
}
// or us
IF (Condition1 && Condition2) || (Condition3 && Condition4)
||! (Condition5 && condition6)) {
DOSMETHINGABOUTIT ();
}
There are three feasible methods here to handle three-yuan arithmetic expression:
Alpha = (AlongBooleaneXpression)? Beta: gamma; alpha = (AlongBooleaneXpression)? Beta
: Gamma;
Alpha = (AlongBooleaneXpression)
? Beta
: Gamma;
5 Note (Comments)
The Java program has two types of annotations: Implementation Comments and Documents (Document Comments). Realizing comments are those who have seen in C , use /*...*/ and // definitions. Document Note (known as "DOC Comments") is a unique java and is defined by / the / **.... Document comments can be converted to an HTML file through the JavaDoc tool.
Realize comments to comment code or implement detail. Document Note describes the code from the perspective of the IMPLEMentation-Free. It can be read by those developers who have no source code.
Note Should be used to give a summary of the code and provide additional information provided by code itself. Note Should only include information related to the reading and understanding procedures. For example, information such as how the corresponding packet is established or in which directory should not be included in the comment.
In the comment, it is possible to explain the important or not obvious place in design decisions, but it should be avoided. Excessive annotations are easy to obsolete. It is usually avoided that the code updates may be more comments.
Note: Frequent comments sometimes reflect the low quality of the code. When you feel forced to add anything, consider rewriting the code clearer.
Comments should not be written in the big boxes drawn in an asterisk or other character. Note Should not include special characters such as patriant characters and backfall.
5.1 Implementation Comment Formats (IMPLEMENTATION China
The programs can have four things that implement annotations: block, single-line, tail, and end-of-line.
5.1.1 Block Comments (Block Comments)
Block comments are typically used to provide descriptions for files, methods, data structures, and algorithms. Block comments are placed at the beginning of each file and before each method. They can also be used elsewhere, such as internal interior. Block note inside features and methods should have the same indentation format with the code they described.
The first block of the block should have a space line, which is used to split the block annotation and code, such as:
/ *
* Here is a block Comment.
* /
Block comments can begin with / *, so that Indenter can identify it as the beginning of a code block without rearing it.
/ * -
* Here Is A Block Comment with Some Very Special
* Formatting That I Want Indent (1) To ignore.
*
* One
* TWO
* Three
* /
Note: If you don't use Indent (1), you don't have to use / * -, or to run Indenter for others in your code.
See "Document Notes"
5.1.2 Single-line Comments (SINGLE-LINE Comments)
Short comments can be displayed in one line and have the same indented level with the subsequent code. If a note cannot be written within one line, it will be used (see "Block Comment"). There should be an empty line before a single line comment. The following is an example of a single-line annotation in a Java code:
IF (Condition) {
/ * Handle the condition. * /
...
}
5.1.3 Tail Note (Trailing Comments)
The extremely short comment can be located in the same row with the code they want, but there should be sufficient blank to separate the code and comments. If there is a plurality of short comments appear in large segment code, they should have the same indentation. The following is an example of the tail end of the Java code:
IF (a == 2) {
Return True; / * Special Case * /
} Else {
Return isprime (a); / * Works Only for ODD A * /
}
5.1.4 Wing Note (End-of-Line Comments)
Comment default "//", you can comment out part of the row or a line. It is generally not used for annotation text; however, it can be used to comment out of the continuous multi-line code segment. The following is an example of all three styles:
IF (foo> 1) {
// Do a double-flip.
...
}
Else {
Return false; // explain why here.
}
// if (bar> 1) {
//
// // do a triple-flip.
// ...
//}
// else {
// Return False;
//}
5.2 Document Notes (Documentation Comments)
Note: Examples of the annotation format described here, see "Java Source File Example"
If you want to know more, see "How to Write Doc Comments for Javadoc", which contains information about document comment tags (@Return, @param, @see):
Http://java.sun.com/javadoc/writingdoccomments/index.html
For more information about document comments and javadoc, see Javadoc's Home:
http://java.sun.com/javadoc/index.html
Document Note Description Java class, interface, constructor, method, and field (field). Each document comment will be placed in the comment delimiter / **...*/, a comment corresponds to a class, interface or member. This comment should be before the declaration:
/ **
* The Example Class Provide ...
* /
Public class example {...
Note that the top-level and interfaces are not indent, and their members are indent. The first row (/ **) describing the document annotation of the classes and interfaces does not need to be indented; the subsequent document comments are indented in each row (align the asterisk). Members, including constructor, the first line of its document comments indent 4 grids, and then indent the 5 grid per line.
If you want to give information about classes, interfaces, variables, or methods, and this information is not suitable for writing in the document, you can use the implementation block annotation (see 5.1.1) or tightly follow the separate note behind the declaration (see 5.1.2). For example, the details of a class implementation should be placed in a block annotation that keeps followed by the class declaration, not in the document comment.
Document comments cannot be placed in a definition block of a method or constructor, since Java will associate the first declaration after the document comment is associated with it.
6 Declarations
6.1 Number per line declared
Recommend a row of a statement, because it is to write a comment. that is,
INT level; // Indentation Level
Int size; // size of table
Be better than
Int Level, Size;
Don't put declarations of different types of variables in the same line, for example: int foo, fooarray []; // wrong!
Note: A space is placed between the type and the identifier between the type and the identifier, and the alternative way to use is a tab:
INT level; // Indentation Level
Int size; // size of table
Object CurrenTry; // Currently Selected Table Entry
6.2 Initialization
Try to initialize while declaring local variables. The only reason not to do this is that the initial value of the variable depends on some previous calculations.
6.3 Layout (Placement)
The variable is declared at the beginning of the code block. (A block refers to any code that is included in the middle of braces "{" and "}".) Do not declare when the variable is used for the first time. This will make the programs that are not concentrated, and the transplantability of the code is hindered in this scope.
Void mymethod () {
INT INT1 = 0; // Beginning of Method Block
IF (Condition) {
INT INT2 = 0; // Beginning of "if" block
...
}
}
One exception to this rule is the index variable of the for loop.
For (int i = 0; i Avoid a local variable that covers a variable of the previous declaration. For example, don't declare the same variable name in the internal code block: INT country; ... mymethod () { IF (Condition) { INT count = 0; // avoid! ... } ... } 6.4 Category and Interface Declaration (Class and Interface Declarations) When writing classes and interfaces, you should follow the following format rules: - Left brackets before the method name and its parameter list "(" do not have spaces - Left braces "{" at the end of the declaration statement - Right Big Brand "}" is one line, aligned with the corresponding statement, unless an empty statement, "}" should follow "{" Class Sample Extends Object { INT IVAR1; INT IVAR2; Sample (int i, int j) { Ivar1 = i; Ivar2 = j; } Int emptymethod () {} ... } - Method and method separation 7 statement (statements) 7.1 Simple STATEments Each line contains one statement, for example: Argv ; // Correct Argc -; // Correct Argv ; argc--; // avoid! 7.2 Composite Statements (Compound Statements) The composite statement is a statement sequence contained in braces, such as "{statement}". For example, the following paragraphs. - Included in which the statement should be more composite statement to indent a level - Left braces "{" should be located at the end of the complex statement; the right braces "}" should be partially rowned and aligned with the complex statement. - Brackets can be used for all statements, including a single statement, as long as these statements are part of the IF-ELSE or FOR control structure. This makes it easy to add a statement without worrying to introduce bugs due to adding parenthesis. 7.3 Return statement (Return Statements) A returnis statement with a return value does not use parentheses "()" unless they make the return value more prominent in some way. E.g: Return; Return mydisk.size (); RETURN (SIZE? SIZE: DEFAULTSIZE); 7.4 IF, IF-ELSE, IF ELSE-IF ELSE statement (IF, IF-ELSE, IF ELSE-IF ELSE STATEMENTS) The IF-ELSE statement should have the following format: IF (Condition) { STATEMENTS; } IF (Condition) { STATEMENTS; } Else { STATEMENTS; } IF (Condition) { STATEMENTS; } Else if (condition) { STATEMENTS; } Else { STATEMENTS; } Note: The IF statement is always enclosed in "{" and "}" to avoid using the following easy format: IF (condition) // avoid! this OMITS The Braces {}! STATEMENT; 7.5 for statement (for Statements) A FOR statement should have the following format: For (inTIALIZATION; UPDATE) { STATEMENTS; } An empty FOR statement (all work is completed in initialization, conditional judgment, updating clause) should have the following format: For (Initialization; Update); When using a comma in the initialization of the for statement or in the update clause, avoiding the use of three variables, resulting in complexity. If necessary, use a separate statement before the FOR cycle (for the initialization subsis) or the FOR cycle (for the update clause). 7.6 While Statement (While Statements) A While statement should have the following format While (condition) { STATEMENTS; } An empty While statement should have the following format: WHILE (CONDition); 7.7 Do-While Statement (Do-While Statements) A Do-While statement should have the following format: Do { STATEMENTS; WHILE (condition); 7.8 Switch statement (Switch Statements) A SWITCH statement should have the following format: Switch (condition) { Case ABC: STATEMENTS; / * Falls through * / Case Def: STATEMENTS; Break; Case XYZ: STATEMENTS; Break; DEFAULT: STATEMENTS; Break; } Whenever a CASE is executed down (because there is no BREAK statement), you should usually add a comment at the location of the BREAK statement. In the sample code above, comments / * falls through * /. 7.9 try-catch statement (Try-catch statements) A try-catch statement should have the following format: Try { STATEMENTS; } Catch (exceptionclass e) { STATEMENTS; } Behind a try-catch statement is also followed by a Finally statement, regardless of whether the TRY code block is successfully implemented, it will be executed. Try { STATEMENTS; } Catch (exceptionclass e) { STATEMENTS; } Finally { STATEMENTS; } 8 blank (White Space) 8.1 Blank Lines The rule is separated from the logical code segment to improve readability. The following conditions should always use two blank lines: - Between two sections of a source file (section) - Class declaration and interface declaration The following conditions should always use an empty line: - Between two methods - Between the first statements of local variables and methods within the method - Block comments (see "5.1.1") or a single line of comments (see "5.1.2") - Between two logic segments within a method to improve readability 8.2 spaces (Blank Spaces) Spaces should be used in the following cases: - A keyword that follows parenthesis should be separated by spaces, for example: While (true) { ... } Note: The space should not be placed between the method name and the left brackets. This will help distinguish between keywords and method calls. - Blank should be in the back of the comma in the parameter list - All binary operators, except ".", You should use spaces to separate from the operand. The one-dollar operator and the operand is not due to the splitter, such as: negative (" ") and self-reduction ("-"). E.g: A = C D; A = (a b) / (c * d); While (D = s ) { N ; } PRINTSIZE ("Size IS" FOO "/ N"); - The expression in the FOR statement should be separated by spaces, for example: For (expr1; expr2; expr3) - It should be followed by a space after compulsory transformation, for example: MyMethod ((Byte) Anum, (Object) x); MyMethod ((int) (CP 5) ((int) (I 3)) 1); 9 Name Specification (Naming Conventions) Naming specification makes the program more readily, making it easier to understand. They can also provide information about identifier functions to help understand code, for example, whether it is a constant, package, or class. Identifier type naming rule example Packages, a unique prefix is always lowercase ASCII letters and is a top domain name, usually in English, org, or 1991 ISO 3166 standard identification country Double character code. The subsequent part of the package is not the same as the naming specification within the respective mechanisms. Such naming specifications may distinguish between departments, projects, or registration names in a specific directory name. Com.sun.eng com.apple.quicktime.v2 edu.cmu.cs.bovik.chese Classs Naming Rules: Class name is a word, using case-by-case mix, the first letter of each word. Try to make your class name simple and description. Use intact words to avoid abbreviations (unless the abbreviation is more widely used, like URL, HTML) Class Raster; Class ImageSprite; Interfaces Name Rules: Sizeless Rules Similar to Class Name Interface RasterDelegate; Interface storing; Method's method name is a verb, which uses cases in cases, and the first letter lowercase of the first word, the first letter of the word thereafter. Run (); Runfast (); GetBackground (); Variables, in addition to variable names, all instances, including classes, types, and small-sized methods, the first letter of the first word, the first letter of the word thereafter. The variable name should not begin with the scribe or dollar symbol, although this is allowed in grammar. The variable name should be short and described. The selection of the variable name should be easy to remember, that is, it can be pointed out. Try to avoid a variable name of a single character unless it is a disposable temporary variable. Temporary variables are usually named I, J, K, M and N, which are generally used for integer; C, D, E, which are generally used for characters. Char C; INT I; Float mywidth; The instance variable (INSTANCE VARIABLES) is similar to the variable name, except for a next line INT _EMPLOYEEID; String _name; Customer_Customer; CONSTANTS, statement, and ANSI constants, should be all uppercase and interconnected interlaced interlaced in words. (Try to avoid ANSI constants, easy to cause errors) Static Final Int min_width = 4; Static Final Int Max_Width = 999; Static Final INT GET_THE_CPU = 1; 10 Programming Formula (Programming Practices) 10.1 Provides access control for examples and class variables (Providing Access To Instance and Class Variables) If there is not enough reason, don't declare an instance or class variable as public. Typically, instance variables do not require explicit settings (SET) and gotten, which is usually produced as the edge effect of method calls (Side Effect). A proper example of a public instance variable is that the class is only the data structure, no behavior. That is, if you want to use a structure rather than a class (if the Java supports the structure), then the instance variable declaration of the class is suitable. 10.2 Reference Class Variables and Class Methods (Referring to Class Variables and Methods) Avoid access to a class of static variables and methods with an object. You should be replaced by a class name. E.g: ClassMethod (); // ok Aclass.classMethod (); // ok Anobject.classMethod (); // avoid! 10.3 Constants In addition to the digital constant of the counter value in the FOR cycle, in addition to -1, 0 and 1, it should not be written directly to code. 10.4 variable assignment (variable assignments) Avoid value to multiple variables in one statement. It is hard to read. E.g: FOOBAR.FCHAR = Barfoo.lchar = 'c'; // Avoid! Do not use the assignment operator to be confused with the equivalent relationship operator. E.g: IF (C = D ) {// Avoid! (Java Disallows) ... } Should be written IF ((C = D )! = 0) { ... } Do not use embedded assignment operators to try to improve the efficiency of runtime, which is the work of the compiler. E.g: D = (a = b c) r; // Avoid! Should be written A = B C; D = a r; 10.5 Other Practices (Miscellaneous Practices) 10.5.1 Parentheses (PARENTHESES) In general, the use of parentheses in an expression containing a variety of operators to avoid operator priority issues, it is a good way. Even if the priority of the operator may be clear, it is not necessary for others. You can't assume that other programmers are as clear as you know the priority of the operator. IF (a == b && c == d) // Avoid! IF ((a == b) && (c == d)) // Right 10.5.2 Return Values Try to make your program structure in accordance with the purpose. E.g: IF (booleaneXpression) { Return True; } Else { Return False; } It should be deprived as the following method: Return BooleaneXpression; Similarly: IF (Condition) { Return X; } Return Y; Should be written: RETURN (CONDition? x: y); 10.5.3 Conditional Operators "?" Expressions Before '?' In The Conditional Operator If an expression containing a binary operator appears in the ternary operator "?:", Then a pair of parentheses should be added to the expression. E.g: (x> = 0)? x: -x; 10.5.4 Special Comments Using XXX in the comment to identify some of the content that does not implement (BOGUS) but works. Use fixme to identify some fake and error content. 11 Code Examples (CODE EXAMPLES) 11.1 Java Source File Example (Java Source File Example) The following example shows how to reasonably layout a Java source program containing a single public class. The layout of the interface is similar. See "Class and Interface Declaration" and "Text Refidence". / * * @ (#) Blah.java 1.82 99/03/18 * * CopyRight (C) 1994-1999 Sun Microsystems, Inc. * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. * All Rights Reserved. * * This Software Is The Confidential and ProPrietary Information of Sun * Microsystems, Inc. ("confidential information"). You Shall Not * Disclose Such Confidential Information and Shall Use IT Only in * Accordance with the Terms of the license agreement you entered Into * With sun. * / Package java.blah; Import java.blah.blahdy.blahblah; / ** * Class Description Goes Here. * * @Version 1.82 18 Mar 1999 * @Author firstname lastname * / Public class blah extends someclass { / * A class implementation common can go here. * / / ** Classvar1 Documentation Comment * / Public static int classvar1; / ** * Classvar2 Documentation Comment That Happens To BE * More Than One Line Long * / Private static object classvar2; / ** Instancevar1 Documentation Comment * / Public Object Instancevar1; / ** Instancevar2 Documentation Comment * / Protected int instancevar2; / ** Instancevar3 Documentation Comment * / Private object [] instancevar3; / ** * ... Constructor Blah Documentation Comment ... * / Public blah () { // ... Implementation Goes Here ... } / ** * ... Method Dosomething Documentation Comment ... * / Public void dosomething () { // ... Implementation Goes Here ... } / ** * ... Method Dosomethingelse Documentation Comment ... * @Param SomeParam Description * / Public void Dosomethingelse (Object SomeParam) { // ... Implementation Goes Here ... } }
