Simple Program Hygiene Rules for Java

Program hygiene, aka style, entails a program's readability and logic structuring. Program hygiene is just as important as correctness in programming. This is useful for you, the programmer, when you are writing code and us, the graders for reading and making sense of a program. Also, in industry and real-world situations, you usually do not write a whole program at once, nor do you only look at programs you wrote. Usually industry programmers are looking at code they did not write or wrote a long time ago, which is where style and comments become very important to understanding programs. (Organizations that want to produce quality software have style guides such as this one.)

Rules to live by.

0. The Golden Rule

It is difficult to enumerate all of the features of good program hygiene and trying to do so in an introductory programming class can be confusing. So we are presenting some simple rules, but keep in mind just because something is not covered here does not mean it isn't an example of BAD program hygiene. The golden rule is your program and code should be easily understood by  another computer scientist, software developer, or programmer.

1. Capitalize class names

public class Thing

2. Do NOT capitalize the first letter of methods or variables

public void methodName() { }

int num1 = 3;

Notice: In the above example, interior letters of method names and variables can be capitalized. Usually when two or more words are combined into one method name or variable name, we capitalize the additional words i.e. methodName. This is sometimes referred to as camelBack.

3. Write comments!

Comments do not have to be excessive; they won't be on every line of a program. However, there should at least be a comment explaining the whole class, comments for each method, and comments for confusing or long parts of the code. If you have good program hygiene and keep your code and methods simpler, the less comments you need.

// comment every method

//and include comments inside the code for tricky parts

4. Use meaningful variable names

int numTokens;

double hypotenuse;

DON'T use double h; or int nT - these are too vague. Also, don't use 10 words in 1 variable - that's too much.

Although they are short names, it's ok to use x or y if they represent coordinates.

i, j, and k are fine for loop control variables if it is they are simply counting out steps of the loop. However, if the loop control variable has more meaning then give it a more meaningful name. For example if the loop control variable represents mass in kilograms use massInKg instead of i.

5. Use constants for constant values

Ex: Above, if you are calculating prices of items, the texasTaxRate will be useful. However, this doesn't change frequently - it is constant. So, in Java you should declare this constant like:

final double TRAVIS_PROPERTY_TAX_RATE = 0.014;

Similarly, if you are using any real world value that is constant, like how much quarters are worth, or what gravity is, declare it final in your program.

Notice: I used all capital letters for the constant, separating words with underscores. This is a widespread Java convention.

6. Indent!

When you declare a class or a method, indent at least 3 spaces to start the next line. All method declarations should line up with each other. Also, when you have an if-statement or a loop-statement, you should always indent the body at least 3 spaces.  You should be fine if you follow any of the indention patterns from the textbook.

You are free to use what every brace style your like best as long as you are consistent.

public class Thing {
 

   public static void main(String[] args) {
      int num = 3;

      for(int i = 0; i <

   } // main

}// Thing

7. Limit the Scope of variables and constants.

Limit the scope of variables and constants to the smallest necessary. This means do not use static variables as a form of global variables. s.

8. Structure and Removing Redundancy.

Use methods (and later, classes) to provide structure to your program and remove redundancy. Methods should do one thing. Methods that grow to 30+ lines of code are often doing multiple things and should be broken into smaller methods to provide an understandable structure.

9. Avoid magic numbers

If you have a literal numeric value in your code, it likely has some meaning. Use a variable or constant to make that meaning clear. Fore any int or double literals besides -1,0, 1, and 2, declare a constant to store that value. You do not have to have constant for literal characters or Strings.

// bad
double bmi = 703.0 * massInLbs / (heightInIn * heightInIn ); // 703? what is that?

// good
final double ENGLISH_UNITS_CONVERSION_FACTOR = 703.0;
double bmi = ENGLISH_UNITS_CONVERSION_FACTOR * massInLbs / (heightInIn * heightInIn );

 

10. Chapter specific rules

For CS312 refer to this document for chapter specific rules for program hygiene.