Style Guide
Borrowed, modified from Keith Trnka and Terry Harvey by Sara Sprenkle
This style guide may not cover all programming best practices, but I'll try to keep it up to date with what you need to get full credit for your programming style.
A program should work the way it's intended to, but simply working
is not enough to be considered really good code. The following are
goals of good programming:
- Performance: Programs shouldn't take too long to run, if possible.
- Readability: If someone looks at your source code, it should be easy for them to understand. The best way for you to understand readability is to read someone else's code and try to figure out what it does.
- Extensibility: If the goals for the program changes, you should be able to change your code relatively easily.
- Ease of debugging: Certain aspects of style reduce the chances of having bugs in your program.
Performance
Performance should not be a big concern for this course. Make sure that your code does not do unnecessary work.Readability
Readability is the main aspect of style that will be graded in this course. There are a few different areas of style for readability, covered below.Comments
- Every function must begin with a block of comments.
- Every
program must begin with a block of comments.
At a minimum, these comments must include name, date, class, section number, and file name, along with a brief description of what the program does. If the program is related to a particular assignment, the assignment and problem number must be included. If the program uses a particular algorithm for solving a problem, you must state that also.
- Do not use comments to make up for using bad names. Spend time on the names instead. Comments should only point out special features of your code, or be used to isolate major sections visually (though this is often better accomplished with whitespace).
Variable and function names
Pick descriptive variable and function names. Don't use abbreviations unless they are obvious. A good test for functions is that you know what the function does by the function name alone. Here are some examples:
| Variables | |
|---|---|
| Good | Bad |
|
distance velocity acceleration |
d ve A b c |
| Functions | |
| Good | Bad |
|
drawPicture squareRoot computePrice |
computeImage (less clear for this case) sqrt total |
Naming conventions
Here are some conventions for naming variables, constants, and functions:- Variables should start with a lowercase letter (as in
meters). In Java, the second word in a variable name is capitalized, such asmilesPerHour. (This is called "Camel Casing" because of the "hump" in the name.) - Classes should start with a capital letter.
- Constants (and only constants) should be all
uppercase (as in
YARDS_PER_METER) - Functions should start with a lowercase letter (as in
computeDistance) - Sometimes you want to user multiple words to name something, such as "rows in file". There are two different conventions for this; pick one.
- Camel Casing: Start the beginning of each word except the first in uppercase:
rowsInFile - Separate words with underscores:
rows_in_file
- Camel Casing: Start the beginning of each word except the first in uppercase:
Indentation
Code should be indented with spaces or tabs so that every statement in the same block of code is lined up. A trick to having good indentation is to press Tab at the beginning of a line in emacs or to select a block of code and choose "indent region". Using an IDE like Eclipse will make indentation even easier.This is an example of good indentation:
int main(void)
{
printf("Hello\n");
printf("Hello again\n");
return 0;
}
This is an example of bad indentation:
int main(void)
{
printf("Hello\n");
printf("Hello again\n");
return 0;
}
There are a few styles of placing curly braces { } in code. I've listed three styles below, but there are probably others; just make sure you stick with one.
- Style 1 (Java style)
int main(void)
{
printf("Hello\n");
printf("Hello again\n");
return 0;
} - Style 2 (Traditional C/C++ style)
int main(void) {
printf("Hello\n");
printf("Hello again\n");
return 0;
} - Style 3
int main(void)
{
printf("Hello\n");
printf("Hello again\n");
return 0;
}
Spacing in equations
When you're typing an equation, make sure to place spaces strategically if the equation becomes too long and unreadable. Here are some examples:
x = x0 + v0 * t + .5 * a * pow(t, 2);
| Good |
x=x0+v0*t+.5*a*pow(t, 2);
| Bad - tough to read |
Program header
You should put a description of your program at the top. That description should include your name and a brief description of what your program does, like so:
/*
Sara Sprenkle (sprenks@udel.edu) 02/07/06
CISC370 Section 040
Assignment 0
This program reads velocities, times, and accelerations from DISTANCE.DAT
and writes out a table of information to DISTANCE.OUT.
*/
Comment alignment
Comments within a section of code should be indented with the code if they are on their own line, as in the following example:
public void main( String args[] ) {
/* shows "Hello" on the screen */
System.out.println("Hello");
/* shows "Hello again" on the screen */
System.out.println("Hello again");
/* exits the program normally */
return 0;
}
Alternatively, comments may be placed on the same line if they are aligned horizontally, like this:
public void main( String args[] ) {
System.out.println("Hello"); /* shows "Hello" on the screen */
System.out.println("Hello again"); /* shows "Hello again" on the screen */
return 0; /* exits the program normally */
}
Vertical spacing
If a bunch of lines of code go together but don't really go with anything else, put a blank line before and after this chunk of code. In the following example, vertical spacing is used in conjunction with comments to section off parts of related code. It isn't really important that you understand the code, just that you see how related chunks of code can be grouped.
Functions
It's much easier to understand a program that has a lot of little functions/methods than a program that has a few big functions. One of the reasons that functions increase readability is that you can usually tell what a function does by its name, even if you don't understand how it's implemented. Consider the following example:
...
printFirstRow(initialVelocity, time, acceleration, computeDistance(initialVelocity, time, acceleration))
...
It should be clear what this code does, even though you don't have
the code for the functions printFirstRow and
computeDistance.
Now look at another way to write it:
...
distance = initialVelocity * time + .5 * acceleration * pow(time, 2);
System.out.printf("%10d%10d%10d%10.1lf", initialVelocity, time, acceleration, distance);
...
Coincidentally, this method of programming helps both debugging and
extensibility. To see how, we need to look at a larger portion of each
program. I've used to comment /* read from file */ as a
placeholder for scanf statements.
| Using your own functions | Without your own functions |
|---|---|
...
|
...
|
Now, suppose that I tell you that your columns are incorrect. Maybe each column should be 15 characters wide instead of 10 characters wide. If you use your own functions, all you need to do is fix those functions. If you did the other way, now you must change every line. This demonstrates how functions can lead to extensible programs. But it's also important for debugging: without functions, you might forget to fix one row or make one typo, but with functions as shown above, you can't make those mistakes.
Putting a statement across multiple lines
Sometimes, one "line" (a sequence of characters that ends with \n) is too long to fit on one line on the screen or printer (usually 80 characters). If that's the case, you can continue it on the next line, indented.Here's some code with a long line:
double meters1, meters2, meters3, meters4, kilometers1, kilometers2, kilometers3, kilometers4, yards1, yards2, yards3, yards4;
You can group things together so that they fit within length of the screen:
double meters1, meters2, meters3, meters4;
double kilometers1, kilometers2, kilometers3, kilometers4;
double yards1, yards2, yards3, yards4;
Sometimes you might do this with a printf too:
System.out.printf("My %d buttons were exploring the Amazon when they discovered that they couldn't eat %d chickens.",
buttons, chickens);
Commenting
You can comment too much and you can comment too little. For instance, on the project, you should describe your general approach, or algorithm, to getting an optimal solution. It's common practice to write a comment before each function, describing the arguments to the function, the return value (if any), and the general idea of the code in the function. However, there are some functions that are self-explanatory and don't require commenting. If you have a large segment of code that does some complicated things, you should comment it just like a function: describe what the variables are like before the code is executed and after the code is executed, and describe your algorithm.You can also comment too much. If you find that you place a comment along with every line of code, you're probably commenting too much. Think about it like this: if you showed your code to someone in the class who doesn't really know you, you should only have comments on the things that they'll have trouble figuring out.
Extensibility
Extensibility is more important when you're more familiar with programming. For the beginning of the class, don't worry about this.Modular design
It sounds big and all, but it really just means that in bigger assignments, you should be able to "plug in" a new function instead of an old one, and it should take care of most of the work of updating your program.Debugging
Incremental Development
Develop and test your program in steps. Look at the programming assignment and "build" up to the complete assignment. For instance, design the interfaces between your classes before implementing the whole classes and use print statements before implementing what a method does so that you know the class interactions are correct.Another way to approach incremental development is to write each method and test it individually.