| CPSC 124 | Introduction to Programming | Spring 2023 |
Programs are written for people just as much as they are written for computers - by far the longest part of the life of real software is the maintenance phase, where programmers may go back for years to fix bugs and add features. It is thus important to make sure they can understand the program.
Having good programming style is also valuable for your own sake - a clear and well-organized program will help your thought processes as you develop the program and will make it easier to find bugs.
Any program that you turn in for this course should obey the rules of good programming style. You will be graded on your programming style, and will lose points for poor style. You can use the programs in the book and those from class (posted on the schedule page) as examples to emulate.
So what is good programming style? The following rules are already relevant:
Put a comment at the beginning of the program containing your name, the name of the assignment, and a brief description of what the program does.
Use a meaningful name for your program so that it is easy to tell from the name which program it is, while avoiding extremely long names.
Use meaningful variable names which suggest the role of the variable in the program, while avoiding extremely long names. Single-letter names are rarely appropriate.
Usually, you should declare each variable on a separate line with a comment explaining the purpose of the variable in the program as well as any other important information about the variable. When several variables are closely related, it can be OK to declare them on the same line (and comment them with a single comment). Comments (or parts of comments) can be omitted if that information is clear from the name of the variable e.g. there's not much to be gained from the comment here
String name; // player's name
if the only thing in the program which could have a name or is identified by its name is the (one) player. It is, however, important to include information not clear from the variable's name, such as
double temperature; // Fahrenheit temperature
Start program names with a capital letter and capitalize the first letter of subsequent words (e.g. HelloWorld or GasCostCalc). Start variable names with a lowercase letter, with capital letters for subsequent words (e.g. lastNumber).
Use indentation to show the structure of the program. Statements surrounded by curly brackets ({ ... }) should be indented relative to the previous level. Follow the examples that you see in class and in the book. With VS Code, utilize the autoformatter to handle this.
Do not have lines longer than 80 characters, and also avoid lines longer than the width of your editor window. (80 characters is the standard for how much text can be printed on one line of paper.) Be careful if word wrapping is turned on - this only makes it look like the line is short enough. Instead use return to split any line that extends past the side of the window or wraps onto a second line. You can split a line almost anywhere other than in the middle of an identifier, operator, or string. Good places are typically right after operators or commas. If you have a long string, you can split it into two parts which are concatenated together (e.g. "really long string" becomes "really long "+"string") and then you can put a line break immediately before or after the +.
Additional rules will be added throughout the course (and can be found in the course programming standards).
A note on commenting: Don't use comments to explain how Java works. Assume that anyone reading a Java source code file knows Java. Instead, include important information that can't be obtained from the code itself.
For example, the following is a useless comment:
double interestRate; // declare a variable named interestRate
It is useless because it repeats exactly what the statement double interestRate; means - someone familiar with Java already knows that is a declaration for a variable named interestRate. The comment doesn't tell the reader anything new.
The following is a better comment:
double interestRate; // declare a variable to hold the annual interest rate
This communicates the purpose of the variable - to hold the interest rate - and provides some important information not apparent from the variable name - that the interest is an annual interest rate, rather than a daily or monthly one. However, it is unnecessarily wordy - there's no need to say "declare a variable to hold" because we can recognize double interestRate; as a variable declaration and that's exactly what a variable declaration does.
The following is the best comment:
double interestRate; // annual interest rate (0-1)
This communicates the purpose of the variable - to hold the interest rate - and provides two pieces of important information not apparent from the variable declaration itself: that this is an annual interest rate (not daily or monthly), and that percentages should be expressed as a decimal between 0 and 1 instead of between 0 and 100. (i.e. 12.5% should be stored as 0.125)