Getting the computer to understand your program is no guarantee that people will be able to follow it. Just as you would edit an English composition, you should spend time revising a computer program to make it elegant and readable. The following guidelines will help you write programs that are easy to read and modify.
Beginning with Assignment 1, the CSE 132 TAs will expect your assignments to conform to these style and documentation conventions. A large portion of your lab grade is based on style, so don't assume that it's good enough to just get your program running. Read this Style Guide carefully, and let us know if you have any questions.
Write a header comment on every file you create.
It should have:
Lab E
)CSE 132 Assignment 4
)Vector.java
)Describe all methods if they are not clear from their name. Err on the side of over-documenting.
In all comments, be brief and informative. Since the CSE 132 TAs are already familiar with the assignment, please don't repeat the details of the assignment. Instead, communicate your approach to solving the problem.
This must be in Javadoc form if writing Java code, which Eclipse can help you write: after typing the method header, go to the line immediately above the method header and type the characters /**
and then press enter
. Eclipse will set up a method comment with the parameter names.
As an example:
/**
* Deposits the given amount into the account.
* REQUIRES: The given amount is positive.
* @param amount the dollar amount to deposit
* @return the new balance
*/
public int deposit(int amount) {
if (amount < 0)
throw new IllegalArgumentException("positive
amount required");
balance += amount;
return balance;
}
Choose meaningful names for all variables, parameters, classes, and methods.
Use complete words instead of abbreviations. For example, use width
instead of w
. However, if an assignment specifies a particular name, please don't choose a different one.
Use named constants instead of sprinkling numbers throughout your code.
For example, if a paint program has a standard brush size of 5 pixels, don't just put the number 5 all over the code. Instead, define and use a constant at the top of the class, like this:
static final int BRUSH_SIZE = 5; // in Java
or
const int SCALE = 3; // in Arduino C
#define SCALE 3 // alternative Arduino C form
This not only makes it easier to read the program, but also simplifies changing the values later because you only have to make the change in one place, where the constant is defined.
Rule of thumb: if a constant is used more than once, give it a name.
Keep your program clear. Your program's logic should be simple. Avoid "clever" tricks that save a line of code at the expense of clarity.
Be especially careful to keep boolean expressions simple. This will ensure readability and will help you avoid logic errors. Also, remember to simply return the value of a boolean expression, rather than testing it in a conditional statement that returns true or false:
// GOOD:
return (height >= level);
// BAD:
if (height >= level) {
return true;
} else {
return false;
}
Follow standard formatting conventions.
int caloriesFromFat = 18;
public class DirectionVector {
public static final double PUPIL_FRACTION = 4;
{
goes at the end of the line before the start of the code block.
the close brace goes on its own line, indented to match the beginning of the line containing the corresponding open brace (an exception is else
which goes on the same line as the closing brace for the corresponding if
, so the closing brace for the if
doesn't appear on its own line)
{}
)
public static boolean withdraw (int amount) {
if (balance < amount) {
return false;
} else {
balance = balance - amount;
System.out.println("Withdrawl of $" +
amount + " successful, leaving $"
+ balance + ".");
return true;
}
}
Tip: Eclipse will help correct your indentation. Select the section of the file you want to correct, and then choose "correct indentation" from the "source" menu.
toString
methodUse brief inline comments whenever the meaning of the code is not immediately obvious. For example, inline comments can be useful to summarize cases in a conditional expression.
if (xPosition < xLeft) // left of box
...
else if (xPosition > xLeft + width) // right of box
...
else if (yPosition < yBottom) // below box
...
else // inside or above box
...
The comment in the following example adds no information and should be omitted since it just wastes the reader's time:
int rectangleWidth = 5; //the rectangle has a width of 5
Be professional. Use the same care in preparing your code as you would for any writing assignment. Avoid jokes in your code, slang terms, crude comments, etc.
Use common sense. Remember that the CSE 132 style guide is only a guide. Your primary concern should be making sure that others can read and understand the text of your program. If you think an additional comment or particular organization will get your ideas across more effectively, do it. However, if you are considering deviating significantly from the guidelines or if you are in doubt about something, discuss it with us first.
Generated at 2024-11-09 20:48:16 +0000.
Page written by Ron Cytron, Josh Gelbard, and Ben Stolovitz.