Capitalization and Commenting Conventions

Capitalization Conventions

By convention, Java programs are written entirely in lower case characters with three exceptions.

• The first letter of class names are capitalized to distinguish class names from member names.
• The names of constant static final fields are written entirely capital letters. For example, thestatic final fields in the preceding subsection are all capitalized according to this convention.
• The first letter in each word of a multi-word identifier after the first is capitalized. For example, the built-in Java class Object includes a method called toString() that we will discuss later. The capital S signifies the beginning of a word within the multi-word name toString().

These conventions are not enforced by Java compilers, but it is considered bad style to violate them.

A related convention is to never use the special character $ in a name; this character is reserved for the use of the Java compiler. Unfortunately, most Java compilers do not enforce this convention.

Commenting Conventions

Java relies on commenting conventions similar to those in C++.

• A comment that is confined to a single line begins with the character sequence // and ends at the end of the line.
• Longer comments must be enclosed between the opening ``bracket'' /* and ``closing'' bracket */.

Examples of both form of comments appear below.

Note that a bracketed comment can appear in the middle of a line of code.

Example

static final string USA = "United States of America";   //constant string

/**  a CityEntry is either:
 *   (i)   a BusinessEntry 
 *         new BusinessEntry(name,addr,phone,city,state),
 *   (ii)  a GovernmentEntry 
 *         new GovernmentEntry(name,addr,phone,city,state,gov), or
 *   (iii) a ResidentialEntry 
 *         new ResidentialEntry(name,addr,phone).
 */
abstract class CityEntry {
}

class BusinessEntry extends CityEntry {

  /* fields */
  String name;	  // The company's name
  String address;  // The company's headquarters street address
  String phone;  // The company's headquarters main business phone
  String city; // The company's headquarters city
  String state;  // The company's headquarters state

  /* constructor */
  BusinessEntry(String n, String a, String p, String c, String s) {
    this.name = n;
    this.address = a;
    this.phone = p;
    this.city = c;
    this.state = s;
  }

  /* accessors */
  String getName() { return this.name; }
  String getAddress() { return this.address; }
  String getPhone() { return this.phone; }
  String getCity() { return this.city; }
  String getState() { return this.state; }	
}

class GovernmentEntry extends CityEntry {

  /* fields */
  String name;	    // Government agency name
  String address;	// Agency headquarters street address
  String phone;	    // Agency headquarters main phone
  String city;	    // Agency headquarters city
  String state;	    // Agency headquarters state
  String government;  // Government that has direct authority over agency

  /* constructor */
  GovernmentEntry(String n, String a, String p, String c, String s, String g) {
    this.name = n;
    this.address = a;
    this.phone = p;
    this.city = c;
    this.state = s;
    this.government = g;
  }

  /* accessors */
  String getName() { return this.name; }
  String getAddress() { return this.address; }
  String getPhone() { return this.phone; }
  String getCity() { return this.city; }
  String getState() { return this.state; }	
  String getGovernment() { return this.government; }	
}

class ResidentialEntry extends CityEntry {

  String name;	  // Individual's name
  String address;  // Individual's main residence
  String phone;  // Main phone number of main residence

  /* constructor */
  ResidentialEntry(String n, String a, String p) {
    this.name = n;
    this.address = a;
    this.phone = p;
  }

  /* accessors */
  String getName() { return this.name; }	
  String getAddress() { return this.address; }
  String getPhone() { return this.phone; }
}

(Written by Corky Cartwright.  Modified by Stephen Wong)