Shulou(Shulou.com)06/02 Report--

This article gives you an analysis of "sample Analysis of Java language coding specifications". The content is detailed and easy to understand, and friends who are interested in "sample Analysis of Java language coding specifications" can follow the editor's idea to read it slowly and deeply. I hope it will be helpful to you after reading. Let's learn more about "sample Analysis of Java language coding Specification" with the editor.

Java language coding specification

1. File name (File Names)

This section lists commonly used file names and their suffixes.

1.1 File suffix (File Suffixes)

The Java program uses the following file suffixes:

File category file suffix

Java source file .java

Java bytecode file .class

1.2 Common file names (Common File Names)

Common file names include:

File name purpose

The preferred file name for GNUmakefile makefiles. We use gnumake to create (build) software.

README outlines the preferred file name for files that contain content in a specific directory

2 document Organization (File Organization)

A file consists of paragraphs divided by blank lines and optional comments that identify each paragraph. Programs with more than 2000 lines are difficult to read and should be avoided. "sample Java source files" provides a well-laid out example of Java programs.

2.1 Java source files (Java Source Files)

Each Java source file contains a single public class or interface. If private classes and interfaces are associated with a public class, you can put them in the same source file as the public class. The public class must be the first class or interface in this file.

The Java source file also follows the following rules:

-opening comments (see "opening comments")

-packages and incoming statements (see "packages and incoming statements")

-Class and interface declarations (see "Class and Interface declarations")

2.1.1 opening comments (Beginning Comments)

All source files should begin with a C-style comment listing the class name, version information, date, and copyright notice:

/ *

* Classname

*

* Version information

*

* Date

*

* Copyright notice

, /

2.1.2 package and incoming statement (Package and Import Statements)

In most Java source files, the first uncommented line is the package statement. It can be followed by an incoming statement. For example:

Package java.awt

Import java.awt.peer.CanvasPeer

2.1.3 Class and interface declarations (Class and Interface Declarations)

The following table describes the parts of class and interface declarations and the order in which they appear. See the sample Java source file for an example that contains comments.

Comments on each part of the class / interface declaration

Class 1 / Interface documentation Notes (/ * * …... * /) for the information to be included in this comment, see "documentation Notes"

Declaration of class 2 or interface

Comments for class 3 / interface implementation (/ *... * /) if necessary, the comment should contain any information about the entire class or interface, which is not suitable for class / interface documentation comments.

Class 4 (static) variables are first public variables of the class, then protected variables, then package-level variables (no access modifiers, access modifier), and finally private variables.

Instance variables are first at the public level, then at the protection level, then at the package level (without access modifiers) and finally at the private level.

6 constructor

7 methods these methods should be grouped by function, not by scope or access. For example, a private class method can be placed between two public instance methods. The goal is to make it easier to read and understand the code.

3 indent typesetting (Indentation)

Four spaces are often used as a unit of indented typesetting. The exact explanation for indentation is not specified in detail (space vs. Tabs). A tab is equal to 8 spaces (instead of 4).

3.1Line length (Line Length)

Try to avoid a line longer than 80 characters, because many terminals and tools can't handle it well.

Note: examples used in documents should use shorter lengths, typically no more than 70 characters long.

3.2 Line feeds (Wrapping Lines)

When an expression cannot fit on a line, you can break it according to the following general rules:

-disconnect after a comma

-break in front of an operator

-prefer a higher level (higher-level) disconnect to a lower level (lower-level) disconnect

-the new line should be aligned at the beginning of the expression at the same level as the previous line

-if the above rules cause confusion in your code or cause your code to pile on the right, indent 8 spaces instead.

Here are some examples of disconnecting method calls:

SomeMethod (longExpression1, longExpression2, longExpression3

LongExpression4, longExpression5)

Var = someMethod1 (longExpression1

SomeMethod2 (longExpression2

LongExpression3))

Here are two examples of breaking arithmetic expressions. The former is better because the break is outside the parenthetical expression, which is a higher-level break.

LongName1 = longName2 * (longName3 + longName4-longName5)

+ 4 * longname6; / / PREFFER

LongName1 = longName2 * (longName3 + longName4

-longName5) + 4 * longname6; / / AVOID

The following are two examples of indent method declarations. The former is a regular case. The latter will move the second and third lines to the right if you use regular indentation, so indent 8 spaces instead

/ / CONVENTIONAL INDENTATION

SomeMethod (int anArg, Object anotherArg, String yetAnotherArg

Object andStillAnother) {

...

}

/ / INDENT 8 SPACES TO AVOID VERY DEEP INDENTS

Private static synchronized horkingLongMethodName (int anArg

Object anotherArg, String yetAnotherArg

Object andStillAnother) {

...

}

The line wrapping of if statements usually uses the rule of eight spaces, because regular indentation (four spaces) makes the body of the statement look laborious. For example:

/ / DON'T USE THIS INDENTATION

If ((condition1 & & condition2))

| | (condition3 & & condition4) |

| (condition5 & & condition6)) {/ / BAD WRAPS |

DoSomethingAboutIt (); / / MAKE THIS LINE EASY TO MISS

}

/ / USE THIS INDENTATION INSTEAD

If ((condition1 & & condition2))

| | (condition3 & & condition4) |

| (condition5 & & condition6)) {

DoSomethingAboutIt ()

}

/ / OR USE THIS

If ((condition1 & & condition2) | | (condition3 & & condition4)

| (condition5 & & condition6)) {

DoSomethingAboutIt ()

}

Here are three possible ways to deal with ternary expressions:

Alpha = (aLongBooleanExpression)? Beta: gamma

Alpha = (aLongBooleanExpression)? Beta

: gamma

Alpha = (aLongBooleanExpression)

? Beta

: gamma

4 comments (Comments)

Java programs have two types of comments: implementation comments (implementation comments) and documentation comments (document comments). Implementation comments are those seen in C++, using / *. * / and / / defined comments. Documentation comments (called "doc comments") are unique to Java and are defined by / *. * /. Document comments can be converted into HTML files through the javadoc tool.

Implementation comments are used to annotate code or implementation details. Documentation comments describe the specification of the code in terms of implementation freedom (implementation-free). It can be read by developers who don't have the source code on hand.

Comments should be used to give a summary of the code and provide additional information that the code itself does not provide. Comments should contain only information related to reading and understanding the program. For example, information such as how the corresponding package is created or under which directory should not be included in the comment.

In comments, it is OK to explain what is important or not obvious in design decisions, but avoid providing repetitive information that has been clearly expressed in the code. Redundant comments can easily become obsolete. You should usually avoid comments that may become obsolete when the code is updated.

Note: frequent comments sometimes reflect the low quality of the code. When you feel compelled to comment, consider rewriting the code to make it clearer.

Comments should not be written in large boxes drawn with asterisks or other characters. Comments should not include special characters such as tabs and fallback characters.

4.1implement the format of comments (Implementation Comment Formats)

Programs can have four styles of implementing annotations: block, single-line, trailing, and end-of-line.

4.1.1 Block comments (Block Comments)

Block annotations are often used to provide descriptions of 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 in other places, such as inside the method. Block comments within functions and methods should have the same indentation format as the code they describe.

There should be a blank line at the beginning of the block comment to separate the block comment from the code, such as:

/ *

* Here is a block comment.

, /

Block comments can start with / *-so that indent (1) can recognize it as the beginning of a code block without rearranging 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 / *-in your code, or make concessions for others to run indent (1) on your code.

4.1.2 single-line comments (Single-Line Comments)

Short comments can be displayed on one line and have the same indentation level as subsequent code. If a comment cannot be written in one line, block comments should be used (see Block comments). There should be a blank line before a single-line comment. The following is an example of a single-line comment in Java code:

If (condition) {

/ * Handle the condition. , /

...

}

4.1.3 tail comments (Trailing Comments)

Very short comments can be on the same line as the code they describe, but there should be enough white space to separate the code from the comments. If multiple short comments appear in a large piece of code, they should have the same indentation.

The following is an example of tail-end comments in Java code:

If (a = = 2) {

Return TRUE; / * special case * /

} else {

Return isPrime (a); / * works only for odd a * /

}

4.1.4 end of line comments (End-Of-Line Comments)

The comment delimiter "/ /" can comment out the whole line or part of a line. It is generally not used for consecutive lines of comment text; however, it can be used to comment out consecutive lines of code. Here are examples 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

/ /}

4.2 documentation comments (Documentation Comments)

Note: for an example of the annotation format described here, see "sample Java source files"

To learn 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 details on documentation comments and javadoc, see the javadoc home page:

Http://java.sun.com/javadoc/index.html

Documentation comments describe Java's classes, interfaces, constructors, methods, and fields (field). Each document comment is placed in the comment delimiter / *. * /, and a comment corresponds to a class, interface, or member. The comment should precede the declaration:

/ * *

* The Example class provides...

, /

Public class Example {...

Note that the classes and interfaces at the top level (top-level) are not indented, and their members are indented. The first line (/ * *) of documentation comments describing classes and interfaces does not need to be indented; subsequent document comments are indented by 1 grid per line (aligning the asterisk vertically). Member, including the constructor, indents the first line of its document comment by 4 squares, followed by 5 squares for each line.

If you want to give information about classes, interfaces, variables, or methods that are not suitable for documentation, you can use implementation block comments (see 5.1.1) or single-line comments immediately after the declaration (see 5.1.2). For example, details about a class implementation should be placed in the implementation block comment immediately following the class declaration, not in the documentation comment.

Document comments cannot be placed in a definition block of a method or constructor because Java associates the first declaration after the document comment.

5 statement (Declarations)

5.1 number of variables declared per line (Number Per Line)

One declaration per line is recommended because it makes it easier to write comments. That is,

Int level; / / indentation level

Int size; / / size of table

Be better than

Int level, size

Do not put the declarations of different types of variables on the same line, for example:

Int foo, fooarray []; / / WRONG!

Note: in the above example, a space is placed between the type and the identifier, and another allowed alternative is to use tabs:

Int level; / / indentation level

Int size; / / size of table

Object currentEntry; / / currently selected table entry

5.2 initialization (Initialization)

Initialize as much as possible while declaring local variables. The only reason not to do so is that the initial value of the variable depends on some previous calculation.

This is the end of the sample analysis of the Java language coding specification. I hope the above content can improve everyone. If you want to learn more knowledge, please pay more attention to the editor's updates. Thank you for following the website!

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.