View on GitHub

CS173

Intro to Computer Science

CS173: Intro to Computer Science - Style Guide

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, a portion of the grade will depend on adhering to these rules.

All rules:

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 Source->Format

Bad Code

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.

?
1
2
3
4
                for (int i = 0; i < 100; i++) {
            if (i%2 == 0 && i%3 == 0)
                    System.out.println(i + " is divisible by 6");
}

Good Code

Here’s a better version of the above example, in which brackets are applied and aligned properly

?
1
2
3
4
5
for (int i = 0; i < 100; i++) {
    if (i%2 == 0 && i%3 == 0) {
        System.out.println(i + " is divisible by 6");
    }
}

Naming Conventions

Bad Code

The names of the variables are not descriptive, and the method is not written as a verb or in camel case.

?
1
2
3
4
5
6
7
8
public static void coolstuff(int x) {
    int myvar = x;
    do {
        System.out.print(myvar + " ");
        myvar = (myvar + 7)%12;
    }
    while(myvar != x);
}

Good Code

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.

?
1
2
3
4
5
6
7
8
public static void printCircleOfFifths(int halfstepInit) {
    int halfstepCurr = halfstepInit;
    do {
        System.out.print(halfstepCurr + " ");
        halfstepCurr = (halfstepCurr + 7)%12;
    }
    while(halfstepCurr != halfstepInit);
}

Documentation: Overview

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

?
1
2
3
4
5
6
/**
* The Stack class represents a last-in-first-out stack of objects.
* @author  Chris Tralie CS 173
* @version 0.1, January 2020
* Note that this version is not thread safe.
*/

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.

Bad Code

?
1
int numCounter;     //counts numbers

Good Code

?
1
2
int numCounter;     // Keeps track of how many
                    // integers the user has entered

Documentation: Methods

All methods will have documentation including, but not limited to:

  1. Method summary
  2. Parameter descriptions
  3. 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 code, 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 Professor Schilling) of what it should look like:

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
/**
 * Returns an Image object that can then be painted on the screen.
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument.
 * <p>
 * This method always returns immediately, whether or not the
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives
 * that draw the image will incrementally paint on the screen.
 *
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */
public Image getImage(URL url, String name) {
    Image image = null;
    try {
        image = getImage(new URL(url, name));
    } catch (MalformedURLException e) {
        e.printStackTrace();
    }
    return image;
 }

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.

Bad Code

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.

?
1
2
3
4
5
6
7
8
9
int i = 0;
int sum = 0;
while (true) {
    if (i >= 10) {
        break;
    }
    sum += Math.pow(2, (double)i);
    i++;
}

Good Code

?
1
2
3
4
int sum = 0;
for (int i = 0; i < 10; i++) {
    sum += Math.pow(2, (double)i);
}

Bad Code

As another example, the code below would be better stylistically in a do while loop

?
1
2
3
4
int choice = rand.nextInt(4);
while (choice==temp){
    choice = rand.nextInt(4);
}

Good Code

?
1
2
3
4
5
int choice = -1;
do {
    choice = rand.nextInt(4);
}
while (choice==temp);

Exiting Appropriately

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 your code)

The Break Command

The 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 code.

Positive Boolean Variable Names

To avoid confusion, boolean variable names should convey the positive case. In other words isReady, isValid, isProperTime are good Boolean variable names. Some not so good names are readyCheck, notValid, checkTime.

Boolean Variable Comparisons

Conditional checks must not compare booleans to true or false.

Example 1:

Bad Code

?
1
2
3
if ((isValid == true) || (isReady == false)) {
    ...
}

Good Code

?
1
2
3
if (isValid || !isReady) {
    ...
}

Example 2:

Bad Code

?
1
2
3
4
5
6
7
8
// This code "toggles" a boolean variable
// back and forth
if (isToggled == true) {
    isToggled = false;
}
else if (isToggled == false) {
    isToggled = true;
}

Good Code

?
1
isToggled = !isToggled;

Breaking Up Long Boolean Statements

Long conditionals should not appear as while or if conditions. Use a boolean variables for readability and self-documentation

Bad Code

?
1
2
3
if ((value <10) || (value >45)) || (response ==”t”) && ((season ==FALL) || (season==SPRING))){
    ...
};

Good Code

?
1
2
3
4
5
6
7
8
//check if price is ok, consumer agrees, and time is right
boolean isReady =   ((value <10) || (value >45))
                    && (response ==”t”)
                    && ((season ==FALL)
                    || (season==SPRING)));
if (isReady){
    //do some stuff
};

Robustness

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.

Bad Code

?
1
2
3
4
5
6
7
// Code to convert a fraction to a decimal
Scanner in = new Scanner(System.in);
System.out.print("Enter numerator: ");
double num = in.nextDouble();
System.out.print("Enter denominator: ");
double denom = in.nextDouble();
System.out.println(num/denom);

Good Code

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Code to convert a fraction to a decimal
Scanner in = new Scanner(System.in);
double num = 0, denom = 0;
do {
    System.out.print("Enter numerator: ");
    num = in.nextDouble();
    System.out.print("Enter denominator: ");
    denom = in.nextDouble();
    if (denom == 0) {
        System.out.println("Cannot have 0 in denominator!");
    }
}
while (denom == 0);
System.out.println(num/denom);

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.

Bad Code

?
1
2
3
4
double Td = 44100/(440*Math.pow(2, 1/12.0));
int T = (int)Math.round(Td);
 
int N = (int)(Math.round(44100*duration));

Good Code

?
1
2
3
4
5
6
7
8
9
10
11
// The sample rate
public static final int FS = 44100;
 
...
 
// Compute the period one halfstep above a 440hz A
double Td = FS/(440*Math.pow(2, 1/12.0));
int T = (int)Math.round(Td);
 
// Compute the number of samples over a particular duration of seconds
int N = (int)(Math.round(FS*duration));

Capitalizing Final Variables

All final variables must be in all caps.

Bad Code

?
1
public static final int secondsInDay = 24*3600;

Good Code

?
1
public static final int SECONDS_IN_DAY = 24*3600;

Methods Returning At The End

Methods may only return at the end of the method, not in the middle

Bad Code

?
1
2
3
4
5
6
public static boolean isEven(int x) {
    if (x % 2 == 0) {
        return true;
    }
    return false;
}

Good Code

?
1
2
3
4
5
6
7
public static boolean isEven(int x) {
    boolean result = false;
    if (x % 2 == 0) {
        result = true;
    }
    return result;
}

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.

Bad Code

?
1
int myInt = Integer.parseInt(in.getLine().charAt(2));

Good Code

?
1
2
3
String inputLine = in.getLine();
char id = inputLine.charAt(2);
int myInt = Integer.parseInt(id);

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.

Bad Code

?
1
2
System.out.println("Enter something");
int x = in.nextInt();

Good Code

?
1
2
System.out.print("Please enter a prime number: ");
int x = int.nextInt();

Variable Scoping

All variable declarations must be within the scope of a method unless the professor gives permission to put a variable within the class scope.

Bad Code

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
int[] refs = {3,28,7,4,9,6,11,8,5,10,7,12};
 
public static int getWeekday(int year, int month, int day) {
    int weekday = 0;
    int ydoomsday=getDoomsdayYear(year);
    int reference = 0;
 
    if(isALeapYear(year);){
        refs[0]=4;
        refs[1]=29;
    }
    reference = refs[month-1];
 
    ...
}

Good Code

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public static int getWeekday(int year, int month, int day) {
    int[] refs = {3,28,7,4,9,6,11,8,5,10,7,12};
 
    int weekday = 0;
    int ydoomsday=getDoomsdayYear(year);
    int reference = 0;
 
    if(isALeapYear(year);){
        refs[0]=4;
        refs[1]=29;
    }
    reference = refs[month-1];
 
    ...
}