# Java Notes: Programming Guidelines

## If a program is useful, it will have to be changed!

If a program is useful, the users will want enhancements, bug fixes, etc. It's also necessary to update programs regularly because the computing environment continuously changes.

Someone has to change them, and surprisingly often, it isn't the original programmer. Therefore, one of the most important characteristics of real programs is that they must be readable and have a style that allows changes. Grading will emphasize readability, programming style, and correctness.

## 1. Readability Problems

### Naming - Very important

- Names of variables, etc should make their use clear. Don't use meaningless or misleading names. In some cases, an arbitrary name must be used, but avoid that if you know what the meaning of the name is. I once worked with someone once who claimed he couldn't think of variable names, so used a, b, c, ... He was a self-taught programmer, and not bad at it in many respects, but no one could every work on his programs - it would be a nightmare working on his programs. Fortunately, he soon switched to management.
- Case: Class names should start with an uppercase character. Variable names should start with lowercase. Constants should be all uppercase.

### Comments, indentation, spacing, ...

- Indentation. Statements must be indented correctly. Every experienced programmer insists on this. Good IDEs will clean up your indentation.
- Header. Program must have comments at top which identify it. These comments should include:
  - Name of directory and file.
  - Purpose of the program. Include both assignment number, and what the program does. A single line is sufficient for most student programs. If you write a program the is not pre-specified for you, the documentation will have to be much more extensive.
  - Your name
  - Date

  I'm flexible about the exact format, but this information should be there.

- "Paragraphs". Statements are should divided into clear sections (like paragraphs), separated by a blank line, and a comment at the beginning telling what this "paragraph" does. Put the comments at the beginning or on the statements they apply to, not at the end of the section.
- Avoid useless comments because they reduce readability. Don't write comments unless they help explain why something is being done, or explain something that is not immediately obvious to the reader.. Just paraphrasing the action of the Java statement makes the program harder to read. For example, the following comment is very bad, even tho it is a true statement.

          fishCount = fishCount + 1;  // Increase fishCount by one.

- One variable declaration per line is a good rule to follow. Putting as many variables as you can on a line saves space (good), but at the expense of readability (bad). Variables declared on their individual lines are easier for a programmer to find, and allow writing a brief common following them. For example,

          int averageRain, n, currentVal, max;

  Might better be written as follows

          int averageRain;   // Average rainfall over all time periods.
          int n;             // Number of time periods.
          int currentVal;    // Amount of rain in the current time period.
          int max;           // Maximum rain in any time period.

- No tabs please. Use multiple blanks instead of tabs. Because there is no fixed specification of how big a tab is, when someone else looks at your program on their system, the alignment of statements is often quite different (and wrong). You would think that relative indentation would be preserved, but in practice the indentation is usually a mix of spaces and tabs, and the result is bad. Some editors, like NetBean's editor, has a reformat source command that will fix everything. Some editors have a "soft tab" option which automatically replaces tabs by blanks. Use it if you have it.

## 2. Programming Style

Additions will be made as more programming concepts are covered.

### Statements

- Proper use of `if` and else `else`.
- Use Loops. If you have code that is repeated, try to generalize it and make it into a loop (while, for, or do..while). Repeating code that should be in a loop is regarded as a major programming sin. Once you become comfortable with loops (and later arrays and methods), this will be easy.
- Always use braces is advice that many good style books give. Avoiding them when the scope of an if or loop contains only one statement is somewhat error prone.

## 3. Correctness and Usability

Naturally a program must run and produce correct output. Unless there are serious problems, the quality of the user interface will not be important in the beginning courses.

### Doesn't compile - no credit

Generally no credit will be given for a program that doesn't even compile.

## Errors and "Happy Trails" Programming

Altho real world programs must handle problem cases, such as illegal input, students may ignore problem cases unless specifically required to do so. The more advanced the course, the more emphasis will be put on handling errors.

But if you do check for errors, observe the following.

- Don't silently ignore errors. If you detect an error, make it known.
- Don't print results that are wrong because you ignored bad input data.