Maintainability. If there's one idea that could serve as a guide to good programming, it's maintainability.
Low cost and more fun. Most of the cost of software, 80% is a frequently used number, is in the maintenance phase: fixing bugs, adding enhancements, adapting it to new systems, etc. That would be a good enough reason to aim for maintainability, but that's not really why I'm saying it. The same things that make software maintainable also make it easier and more pleasant to work on in the first place. Sometimes it takes a few extra key strokes or an extra moment of thought, but those are usually quickly repaid.
Factors. Three topics that cover a lot of the maintainability territory are:
If a program is useful, users 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.
Program must have comments at top which identify it. Which include:
The exact format is, but all information must be there.
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.
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. BAD
There are two good styles for declaring variables, and one bad style.
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.
Programmers universally agree that good indentation is required.
There are standard ways to use white space (blanks, and newlines) to make programs easier to read.
y = f(x)", not "y = f (x)".
if (a < b)", not "if(a < b)".
Minimize distance between declaration and use. It is probably much easier to read code if the distance between declaration and use is minimized. This argues for declaring variables at their first use.
Inner scope. Generally variables should be declared at the innermost scope that they are needed at. This is way a for loop variable should be preferably declared in the loop header. All local variables are allocated when a method is entered, even if they are in an inner block, so there is no extra allocation penalty as is sometimes mistakenly claimed.
See Programming in the small - variable declarations (ivan.truemesh.com/archives/000596.html) for a discussion of this.
Naming is perhaps the single biggest contributor to readability.
If names are well chosen, comments aren't so important.
Real world programs must handle problem cases, such as illegal input, but beginning students may ignore problem cases unless specifically required to do so. The more advanced the course, the more emphasis is put on handling errors.
The general rule is that variables should be private, and methods public. That's a good starting point.
static final), you should rarely have static variables. Static methods are appropriate if they don't depend on instance variables.
Exception- make it more specific.
Sun's guidelines. Perhaps the most common coding guidelines are Sun's Code Conventions for the Java Programming Language, which can be read online of downloaded in several forms from java.sun.com/docs/codeconv/. My guidelines are basically theirs with a few changes.