A.10. Coding Conventions

This section describes the standard coding style we will use in this book. You or your instructor may have slightly different preferences. Since coding style exists to make programs easier for humans to read, it is only important that we are consistent and stay fairly close to what most of the Java community does.

Identifiers

Names of constants are in all caps, with words separated by underbars:

PI
SCREEN_WIDTH

Type parameters (Section 4.1) have one-letter upper-case names. Typical names include E for element, K for key, and V for value.

Names of classes, constructors (Section 1.2), and interfaces (Section 2.3) have words run together, with the first letter of each word capitalized:

Hello
PolyhedralDie

All other identifiers are formatted the same way, but the first word is not capitalized:

args
bestSoFar

A few standard identifiers are given in Figure A-22.

Figure A-22. Widely used identifiers.

Identifier

Use

i, j, k

loop variable, index into array

m, n

integer in mathematical function

tally

running count of something

target

element being searched for in, removed from, or added to a data structure

that

object being compared with this

result

value to be returned

x, y

double in mathematical function

 

Blocks

We always use curly braces for the bodies of loops and if statements. It is technically legal to leave these out if the body consists of a single statement, but it is a very bad idea. If we later go back and add another line (for example, an invocation of System.out.println() to print a debugging message), we might run into the problem shown in Figure A-23.

Figure A-23. These two for loops are not equivalent.

1 for (int i = 0; i < 5; i++) {
2 System.out.println("i is " + i);
3 System.out.println("I'm in the loop!");
4 }
5
6 for (int i = 0; i < 5; i++)
7 System.out.println("i is " + i);
8 System.out.println("I'm in the loop!");

Despite the deceptive indentation, these loops are not equivalent. In the second loop, the body of the loop is only line 7. Line 8 is not in the loop, so it is executed only once.

Comments

We include a javadoc comment before each class, interface, field, and method, with the exception of some methods which are merely implementing a method from an interface (Section 2.3) or overriding a method from a superclass (Section 3.1). A javadoc comment begins with /** and ends with */.

The wonderful thing about javadoc comments is that they can be used to generate automatic documentation.

Warning: Do not perform this next step if you have any .html files in the same directory as your .java files. The javadoc program may overwrite them!

By this point you presumably have several .java files in your directory. To generate documentation for all of them, use the command:

javadoc -public *.java

This generates a number of .html files. Open the file index.html in your web browser. Click on the name of a class to see its documentation. Part of the documentation for the Circle class (Figure A-17), in the file Circle.html, is shown in Figure A-24.

Figure A-24. Part of the automatically-generated javadoc documentation for the Circle class.

(This item is displayed on page 541 in the print version)

A second type of comment is the C++-style comment which begins with // and goes to the end of the line. We occasionally use this to point out the major sections of a method, explain a particularly cryptic line, or note that some code has been left out of a figure for brevity.

Access Levels

Access levels are discussed in Chapter 3. We adopt the following conventions:

All fields are private, except for constants, which are public.

Methods are either public or protected.

All classes and interfaces are public.

Arrangement of Class Members

The elements of a class appear in the following order:

  1. Static fields
  2. Non-static fields
  3. Constructors
  4. Other methods
  5. The main() method

Within each section, members appear in alphabetical order, unless some other order (particularly for fields) would be clearer.

Exercises

A.23

Discuss the advantages and disadvantages of establishing coding conventions for a group project.

A.24

In what way does the method name println() violate the standards?


Part I: Object-Oriented Programming

Encapsulation

Polymorphism

Inheritance

Part II: Linear Structures

Stacks and Queues

Array-Based Structures

Linked Structures

Part III: Algorithms

Analysis of Algorithms

Searching and Sorting

Recursion

Part IV: Trees and Sets

Trees

Sets

Part V: Advanced Topics

Advanced Linear Structures

Strings

Advanced Trees

Graphs

Memory Management

Out to the Disk

Part VI: Appendices

A. Review of Java

B. Unified Modeling Language

C. Summation Formulae

D. Further Reading

Index



Data Structures and Algorithms in Java
Data Structures and Algorithms in Java
ISBN: 0131469142
EAN: 2147483647
Year: 2004
Pages: 216
Authors: Peter Drake

Similar book on Amazon

Flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net