CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Programming Style Guide
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Table of contents
Introduction ........................................................................................................................................................................... 3
Guide 1: Include program header comments ........................................................................................................................ 4
Guide 2: Comment complex portions of your code ............................................................................................................... 5
Guide 3: Line lengths should not pass a specified limit.......................................................................................................... 6
Guide 4: Follow naming conventions ..................................................................................................................................... 7
Guide 5: Use proper and consistent indentation ................................................................................................................... 8
Guide 6: Use blank spaces and blank lines to delineate code .............................................................................................. 10
Guide 7: Include method header comments (except main) ................................................................................................ 13
Guide 8: Separate methods with single blank line ............................................................................................................... 14
Guide 9: Delete any extraneous code that is not used ........................................................................................................ 15
Guide 10: When points will be deducted for style issues .................................................................................................... 16
2
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Introduction
The style in which you code your program is just as important (and arguably more important) as having a correct
program. While having good comments or good variable names does not affect the correctness of a program, it will
affect your grade. Writing a program that is easy to read and maintain is critical on a job. It is important that others who
may not be familiar with your code be able to understand your code in case they need to modify it. For this reason, it is
important to get into the habit of using good style from the beginning.
Therefore, a portion of your score in programming assignments will depend on how well you are following this
programming style guide. This guide will help you better understand what we are looking for when we look at your
assignment submissions. Make sure to read the problem specifications, in case we are specifically looking for a particular
style implementation during grading. Before submitting your program for grading, be sure to double-check your style of
coding and documentation. As the semester progresses, there will be steeper penalties for every style mistake.
In general, your programs should be organized, formatted, and indented so that it is neat and easy to read. Follow the
code examples in lecture to see examples of proper formatting. Tip – prior to submitting your program for grading,
always use the IntelliJ IDEA's Reformat code command the Code menu option. This will help make your program more
readable.
3
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Guide 1: Include program header comments
At the top of each program (or Java file), you should write your name, VUnetID, email address, section, date of creation,
an honor statement, and a brief description of what the program is for.
DO
// Name: Cornelius Vanderbilt
// VUnetID: vandercc
// Email: [Link]@[Link]
// Class: CS 1101 - Vanderbilt University
// Section: 1
// Date: 01/01/2021
// Honor statement: I attest that I understand the honor code for this class and have neither
// given nor received any unauthorized aid on this assignment.
// Program description: This program selects the winning numbers for the Powerball lottery.
For the honor statement, don't just write "agree" or "signed". It must be a full honor code statement. You may use the
statement given in the example above.
DON'T
// Honor statement: I agree.
DON'T
// Honor statement: Signed.
For the program description, don't just write the title of the programming assignment problem. Write a brief description
of what the program does.
DON'T
// Program description: PA03 Powerball
4
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Guide 2: Comment complex portions of your code
If the code in a method is simple you do not need to comment in the method body. If the code in the body of the
method is complex, you might want to add some comments to certain areas that you deem to be complex.
Be careful not to over comment! Over commenting can make the program hard to read just as much as under-
commenting. Do not comment every line. If they are simple instructions, most people will understand them without
your comments. If you think you need commenting, try commenting chunks of code under the same comment.
DO
public static void main(String[] args) {
// Computes the length of the hypotenuse based on user input.
[Link]("Input lengths of shorter triangle sides:");
Scanner console = new Scanner([Link]);
[Link]("a: ");
double a = [Link]();
[Link]("b: ");
double b = [Link]();
double c = [Link](a * a + b * b);
[Link]("The length of the hypotenuse is " + c);
}
DON'T
public static void main(String[] args) {
// Computes the length of the hypotenuse based on user input.
[Link]("Input lengths of shorter triangle sides:");
// Declare and initialize Scanner object for console.
Scanner console = new Scanner([Link]);
// Asks for the length for side a.
[Link]("a: ");
double a = [Link]();
// Asks for the length for side b.
[Link]("b: ");
double b = [Link]();
// Compute the length of the hypotenuse.
double c = [Link](a * a + b * b);
// Print the length of the hypotenuse.
[Link]("The length of the hypotenuse is " + c);
}
5
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Guide 3: Line lengths should not pass a specified limit
Any line of code or comments that is over 80 characters may not print correctly on a standard printer. For this reason,
you should consider revising or writing code (or comments) on multiple lines where it would exceed 80 characters.
For CS 1101, we allow a buffer of 20 additional characters. In other words, for any single line (code or comment), you
can have utilize up to 100 characters (sometimes also called columns). Any line that goes beyond 100 characters will
cause your program to incur a deduction.
All lines in the program must not exceed the limit, including lines containing only comments.
An IDE (e.g., IntelliJ IDEA) will typically show how much characters you have used in a line at the bottom right of the
window. In the screenshot below, on the bottom right, the text 7:100 means that the cursor (black vertical line after the
word "neither") is on line 7 and column 100. Do not use a website that says it counts characters in lines.
VERTICAL LINE
REFERENCE
SPECIFIES LINE AND
COLUMN NUMBER
The PyCharm IDE also includes a gray vertical line that can be used to visually see the 100th column directly in the editor
(i.e., the vertical gray line in the source code editor in the screenshot above). The default location of this vertical line is
not at 100 characters when the IDE is installed. You will need to edit the settings for this line. Select IntelliJ IDEA |
Preferences for MacOS or File | Settings for Windows and Linux. Then select Editor | Code Style. For Hard wrap at set
the value to 100 and then press OK.
6
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Guide 4: Follow naming conventions
Use the following naming conventions for the names you use to identify variables, constants, classes, and methods.
1. Variable and method names. Should start with a lowercase letter, with words separated by a capital letter for each
first letter of each word.
2. Constant variable names. Should be all capital letters with underscores separating words.
3. Class names. Every word in the name should start with a capital letter. Note that we will only see classes in the latter
part of the semester.
Additional notes:
- Choose meaningful names. Names that have nothing to do with the program are bad names. For example, using
frodo as the name of a variable to store the area of a rectangle.
- Choose descriptive and specific names. Names that are not specific or descriptive enough are generally bad names.
For example, using the name line or l (i.e., the letter 'L' in lowercase) for a variable are not as good as using the
name vertLine , if the line represents a vertical line. The previous example that used a , b , and c , is okay, because
those are the letters typically used in the Pythagorean Theorem.
- Try not to name objects sequentially. You should only do this when the objects are related in some way that is not
otherwise expressible. For example, the variable names group1 and group2 are not as good as darkClothes and
whiteClothes if they represent separating a pile of laundry.
DO DON'T
// A variable to store the height of a house. // A variable to store the height of a house.
int houseHeight = 50 int frodo = 50
int hh = 50
int house_height = 50
// Variables to store piles of laundry. // Variables to store piles of laundry.
int darkClothes = 5 int clothes1 = 5
int whiteClothes = 10 int clothes2 = 10
// A function to calculate an area. // A function to calculate an area.
public static double calcArea() { ... } public static double ca() { ... }
public static double calc_area() { ... }
// A constant for the number of days in a week. // A constant for the number of days in a week.
public static final int DAYS_IN_WEEKS = 7 public static final days_in_week = 7
public static final DAYSINWEEKS = 7
// A class representing a bank account. // A class representing a bank account.
public class BankAccount { ... } public class bankAccount { ... }
public class Bank_Account { ... }
public class BANK_ACCOUNT { ... }
7
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Guide 5: Use proper and consistent indentation
Consistent indentation also helps make the code more readable as their use signifies what part of the program a
statement is part of. Methods that are part of a class should be indented to signify that they are part of the class.
Statements inside the methods should be indented to signify that they are part of the method. Furthermore, statements
that are part of a conditional statement or loop should also be indented appropriately.
DO
public class Indentation {
public static void main(String[] args) {
Scanner console = new Scanner([Link]);
[Link]("Enter number: ");
double num = [Link]();
if (num < 0) {
[Link]("Number is negative.");
} else {
[Link]("Number is zero or positive");
for (int i = 0; i < num; ++i) {
[Link](i);
}
}
}
}
DON'T
import [Link].*;
public class Indentation {
public static void main(String[] args) {
Scanner console = new Scanner([Link]);
[Link]("Enter number: ");
double num = [Link]();
if (num < 0) {
[Link]("Number is negative.");
} else {
[Link]("Number is zero or positive");
for (int i = 0; i < num; ++i) {
[Link](i);
}
}
}
}
8
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Press the Tab key when you want to indent a line. In IntelliJ IDEA, by default, four empty spaces are added. Make sure
to properly and consistently indent your code.
9
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Guide 6: Use blank spaces and blank lines to delineate code
Blank spaces in a statement helps make the code more readable. Blank lines are used to delineate different areas of the
code. In addition, there should always be one blank line between methods. It is also advisable to break up long method
bodies and long declarations into logical pieces.
DO
public static void main(String[] args) {
// Computes the length of the hypotenuse based on user input.
[Link]("Input lengths of shorter triangle sides:");
Scanner console = new Scanner([Link]);
[Link]("a: ");
double a = [Link]();
[Link]("b: ");
double b = [Link]();
double c = [Link](a * a + b * b);
[Link]("The length of the hypotenuse is " + c);
}
There is no specific rule determining when we need to insert blank lines between code lines. However, if you find a few
lines of code collectively doing a specific task, then separate them from the code before and after with blank lines. The
following is still okay, because the grouped code performs a collected task.
DO
public static void main(String[] args) {
// Computes the length of the hypotenuse based on user input.
[Link]("Input lengths of shorter triangle sides:");
Scanner console = new Scanner([Link]);
[Link]("a: ");
double a = [Link]();
[Link]("b: ");
double b = [Link]();
double c = [Link](a * a + b * b);
[Link]("The length of the hypotenuse is " + c);
}
10
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
However, blank lines should delineate sections of code that do separate things. Just like writing term papers, you don't
just write the whole paper in one big paragraph. Well, unless you were writing the Magna Carta!
DO
public static void main(String[] args) {
Scanner console = new Scanner([Link]);
// Computes the length of the hypotenuse based on user input.
[Link]("a: ");
double a = [Link]();
[Link]("b: ");
double b = [Link]();
double c = [Link](a * a + b * b);
[Link]("The length of the hypotenuse is " + c);
// Computes the Body Mass Index (BMI).
[Link]("height: ");
double height = [Link]();
[Link]("weight: ");
double weight = [Link]();
[Link]("The BMI is " + height / weight ** 2);
}
DON'T
public static void main(String[] args) {
Scanner console = new Scanner([Link]);
// Computes the length of the hypotenuse based on user input.
[Link]("a: ");
double a = [Link]();
[Link]("b: ");
double b = [Link]();
double c = [Link](a * a + b * b);
[Link]("The length of the hypotenuse is " + c);
// Computes the Body Mass Index (BMI).
[Link]("height: ");
double height = [Link]();
[Link]("weight: ");
double weight = [Link]();
[Link]("The BMI is " + height / weight * weight);
}
11
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Similarly, blank spaces should be used at appropriate parts in a single statement (see example at top of page). Without
these blank spaces, the statement will be harder to read.
DON'T
public static void main(String[] args) {
Scanner console = new Scanner([Link]);
// Computes the length of the hypotenuse based on user input.
[Link]("a: ");
double a=[Link]();
[Link]("b: ");
double b=[Link]();
double c=[Link](a*a+b*b);
[Link]("The length of the hypotenuse is "+c);
// Computes the Body Mass Index (BMI).
[Link]("height: ");
double height=[Link]();
[Link]("weight: ");
double weight=[Link]();
[Link]("The BMI is "+height/weight*weight);
}
12
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Guide 7: Include method header comments (except main)
Before each method heading (i.e., the line containing the keywords public static ), there should be a brief description
of what the method does followed by parameter descriptions, and a description of the return value. You do not need to
do this for the main method.
- All comment lines should be indented the same as the method header line.
- The comments should start with /** on its own line.
- Provide a brief description what happens when the subprogram is called. Your comments should describe the intent
of the code. What are you trying to accomplish with this piece of code?
- Each parameter should be listed with a brief description of the parameter. Precede each parameter listing with
@param .
- You do not need to write anything about parameters if the method does not accept any parameters.
- If the method returns something, include a description of what is returned. Precede the description of what is
returned with @return .
- You do not need to write anything about a return value if the method does not return anything.
- The comments should start with */ on its own line.
The following is an example for a function called getImageURL . The function accepts two parameters: url and name ,
and based on the comments returns a value.
DO
/**
* Returns an Image object that can then be painted 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.
*/
public static Image getImageURL(URL url, String name) {
...
}
13
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Guide 8: Separate methods with single blank line
Method definitions should be separated by one line.
DO
/**
* Determines whether number passed is an even number.
*
* @param num The number to determine whether it is even or not.
* @return True if the number is even and false otherwise.
*/
public static boolean isEven(int num) {
return num % 2 == 0;
}
/**
* Determines whether number passed is an odd number.
*
* @param num The number to determine whether it is odd or not.
* @return True if the number is odd and false otherwise.
*/
public static boolean isOdd(int num) {
return num % 2 == 1;
}
DON'T
/**
* Determines whether number passed is an even number.
*
* @param num The number to determine whether it is even or not.
* @return True if the number is even and false otherwise.
*/
public static boolean isEven(int num) {
return num % 2 == 0;
}
/**
* Determines whether number passed is an odd number.
*
* @param num The number to determine whether it is odd or not.
* @return True if the number is odd and false otherwise.
*/
public static boolean isOdd(int num) {
return num % 2 == 1;
}
14
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Guide 9: Delete any extraneous code that is not used
You would not hand in an English paper with crossed out lines. Similarly, you should not hand in an assignment with
commented out code that you do not want executed. Remove all coding lines that you comment out.
DON'T
public static void main(String[] args) {
// Computes the length of the hypotenuse based on user input.
[Link]("Input lengths of shorter triangle sides:");
Scanner console = new Scanner([Link]);
[Link]("a: ");
double a = [Link]();
[Link]("b: ");
double b = [Link]();
double c = [Link](a * a + b * b);
[Link]("The length of the hypotenuse is " + c);
// I wonder if I can combine the last two statements?!
// [Link]("The length of the hypotenuse is " + [Link](a*a + b*b));
}
15
CS 1101 | PROGRAMMING AND PROBLEM SOLVING
Guide 10: When points will be deducted for style issues
The following table shows when certain style issues will be deducted points. A style issue is deducted in a programming
assignment if there is a dot for that style issue in the table.
Note that initially no points are deducted for style issues. As the semester progresses, certain style issues will be
deducted points. The maximum allowable points that can be deducted for style issues will also gradually be increased as
the semester progresses.
Programming assignment
Style issue
00 01 02 03 04 05 ⭐
Header comments1 • • • • •
Honor code1 • • • • •
Program description1 • • • • •
100 character line length3 • • • •
Identifier name format4 • • • •
Meaningful identifier name4 • • • •
Proper and consistent indentation5 • • • •
Proper use of blank spaces6 • • • •
Proper use of blank lines6 • • • •
Method header comments7 • •
Method header comment style7 • •
Parameter/return value description7 • •
One blank line between methods8 • •
"Remaining programming assignments.
1
See Guide 1.
3
See Guide 3.
4
See Guide 4.
5
See Guide 5.
6
See Guide 6.
7
See Guide 7.
8
See Guide 8.
16