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

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

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:

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.

  1. Style 1 (Java style)

    int main(void)
         {
         printf("Hello\n");
         printf("Hello again\n");
         return 0;
         }

  2. Style 2 (Traditional C/C++ style)

    int main(void) {
         printf("Hello\n");
         printf("Hello again\n");
         return 0;
    }

  3. 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
...
/* read from file */
printFirstRow(initialVelocity, time, acceleration,
     computeDistance(initialVelocity, time, acceleration))
/* read from file */
printOtherRow(acceleration,
     computeDistance(initialVelocity, time, acceleration))
/* read from file */
printOtherRow(acceleration,
     computeDistance(initialVelocity, time, acceleration))
...
...
/* read from file */
distance = initialVelocity * time
     + .5 * acceleration * pow(time, 2);
System.out.printf("%10d%10d%10d%10.1lf",
     initialVelocity, time, acceleration, distance);
/* read from file */
distance = initialVelocity * time
     + .5 * acceleration * pow(time, 2);
System.out.printf("%30d%10.1lf", acceleration, distance);
/* read from file */
distance = initialVelocity * time
     + .5 * acceleration * pow(time, 2);
System.out.printf("%30d%10.1lf", acceleration, distance);
...

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.