CS173: Intro to Computer Science - Style Guide
As we’ve discussed and experienced, it’s possible to write code that works, but which is completely unreadable and difficult to debug as a result. Furthermore, we want to get you into the habit of writing good code that is easy for others to read and which is hence easier to maintain. In practice, if people can’t read your code, they’ll just do it over from scratch their own way. It would be a shame for all of your hard work to go to waste!
Below are some rules to help keep you on the rails as you design (they have been adapted from Professor Schilling and from Professor Tralie). On many assignments, 10% of the grade will depend on adhering to these rules.
- Naming Conventions
- Documentation: Overview
- Documentation: Inline Code
- Documentation: Methods
- Appropriate Loop Choices
- Exiting Appropriately
- The Break Command
- The GOTO Command
- Positive Boolean Variable Names
- Boolean Variable Comparisons
- Breaking Up Long Boolean Statements
- No Magic Numbers!
- Capitalizing Final Variables
- Methods Returning At The End
- Efficiently Written Code
- Avoid Compound Method Calls
- Text Input Prompts
- Variable Scoping
Indentation / Brackets
All code must follow proper indentation and bracket conventions. This
includes, but is not limited to, conditionals, loops, and methods.
Brackets should be at the end of each if statement, even if the body
contains only one line. You should get into the habit of setting up your
brackets and tabbing when you first complete a method, loop, or
conditional statement, but before you type anything in it. If you go
completely off the rails, Netbeans can save you if you click
First of all, this code is missing brackets around the if statement. This makes it easy to have a bug if you decide to add the line, because only the first line is considered to be in the body of the if statement. Second of all, the tabbing is all over the place. This makes it easy to miss a closing brace somewhere, which can be very difficult to resolve for multiply nested blocks.
Here’s a better version of the above example, in which brackets are applied and aligned properly
- Variable and method names should be in camel case; that is, the first letter should be in lower case, and each new word should be capitalized, with no spaces or underscores in between the words.
- Variables and methods should be descriptive of what the variable holds.
- For loop counters should be something short such as
k. You may also use a descriptive, but still short, name for a for loop counter such as
- Method names should start with a verb (this includes boolean methods that start with the verb “is”).
The names of the variables are not descriptive, and the method is not written as a verb or in camel case.
The method is now a verb that describes what it does, and its name and all variables are written in camel case (assuming “halfstep” is one word) and in descriptive language.
All files must have comments near the top of the main program’s file containing the following information: Author’s name, Assignment name, Date, Class, Short description of the project. For complete information on writing Java documentation, visit this link or this link. As an example, here’s a comment at the top of a file
Documentation: Inline code
All variables (except for loop counters) must be documented. Do not state the obvious. This clutters up your code and does not convey any information to the reader.
All methods will have documentation including, but not limited to:
- Method summary
- Parameter descriptions
- Return value descriptions
These comments should appear above the method name in a particular
format, which makes it easy to automatically generate web pages
describing the code (for instance, see documentation for the audio
which was generated this way). In NetBeans, if you
type out the definition of the method and then type
/** followed by
ENTER, it will automatically generate a correctly formatted comment,
which you can fill in with details. Below is an example (courtesy of
of what it should look like:
Appropriate Loop Choices
Code will be graded on appropriate loop choice. Using a while where a for loop is more appropriate will result in a deduction. You should use a do while loop where appropriate. Breaking out of a loop for any condition aside from the loop control will result in a deduction.
Since the loop below starts at 0 and stops at 9, a for loop is much more appropriate. Furthermore, the code uses a break statement, which can be confusing.
As another example, the code below would be better stylistically in a do while loop
Ending the program anywhere except for the last line of the main will
result in a deduction. (In other words, no
exit(0) in the middle of
The Break Command
break command should only appear in a
switch statement, and not
in a loop.
The GOTO Command
Do not use
goto anywhere in your code! It is an artifact from older
programming languages and leads to spaghetti
Positive Boolean Variable Names
To avoid confusion, boolean variable names should convey the positive
case. In other words
isProperTime are good
Boolean variable names. Some not so good names are
Boolean Variable Comparisons
Conditional checks must not compare booleans to
Breaking Up Long Boolean Statements
Long conditionals should not appear as
if conditions. Use a
boolean variables for readability and self-documentation
All input must be checked. Bad input must be handled gracefully; code must not crash on any inputs. Bad input must not be handled silently. If the user gives bad input, they must be notified and given a choice to re-enter or quit the program.
No Magic Numbers!
A “magic number” is a number in the program that should be defined as a final constant, especially if it’s used more than once, since the programmer only has to update it in one place to change all instances.
Capitalizing Final Variables
All final variables must be in all caps.
Methods Returning At The End
Methods may only return at the end of the method, not in the middle
Efficiently Written Code
Code must be efficient as possible without sacrificing readability. This includes, but is not limited to chaining your if statements, using the least amount of variable declarations as possible, and using the smallest data type necessary. For instance, if the user is to answer 1,2,3,4 as a response, use an int, not a double.
Avoid Compound Method calls
Compounding methods and parameters makes your code difficult to read and debug, so split up method calls using variables when appropriate.
Text Input Prompts
Prompts must be meaningful and input must appear on the same line as the prompt. There must be a space between the prompt and the input the user gives.
All variable declarations must be within the scope of a method unless the professor gives permission to put a variable within the class scope.