The Definitive CS106 Style Guide
The Definitive CS106 Style Guide
Table of Contents:
Why Should I Care about Style?
Good Naming
Commenting
Decomposition
Whitespace
Instance vs. Local Variables
Elegant Code Structure
Always Use Constants:
General and Reusable Methods:
There Are Many Ways To Solve the Same Problem:
Short Methods:
Why Should I Care about Style?
It's common when you're writing code to think it's self- explanatory. However, for anyone (yourself included) who's seeing code either for the first time or for the first time in a few days, the way the code works isn't always immediately obvious. The reason good style is important is because well-structured, easy-to-read code is easier to modify, easier to debug and easier to work with. This is something that will save you hours of work.
When in doubt as to whether you should do something for style reasons ("should I comment this line?"), just remember the spirit of code style: the object is to make your code as readable as possible. Here are some tips to make your programming style better and the life of anyone reading it much easier!
Good Naming
Use meaningful names, but don't go overboard. Suppose you have a variable in your program that holds the number of hours employees worked in a week:
/*OK, but not very descriptive*/
int hours = 40;
/*much more descriptive, but cumbersome*/
int hoursTheWorkersWorkedInOneWeek = 40;
/*a good compromise*/
int hoursPerWeek = 40;
Common abbreviations are often acceptable in variable names, like hrsPerWeek. But don't get carried away; hrsPWk simply is not a good name.
Part of good style is good naming. You want your method name to succinctly describe what it does. Never call a method doStuff, give it a good specific name like isOdd. Be consistent in how you name your methods. In our solutions, we will use lower camel case naming conventions.
Commenting
Make sure to comment every method you write, and describe what the method does, and what the assumptions are before and after it is called. Write your comments so that your program could easily be understood by another person.
In general, remember to have one comment describing the entire program, then
a few lines above the function header for each function describing the purpose of the function,
plus any pre-conditions or assumptions of the function and maybe some lines elaborating upon
the parameters if necessary. It's also good to comment when you're writing code that deals with
an edge case or when your code refers to other sections of your code so the reader doesn't have to scroll everywhere. Commenting is best done while coding, not after you’ve finished.
But there's such a thing as too much of a good thing. To illustrate, here's an example of over- commented code:
for (int /*i is of type int*/ i = 0 /*initializing the variable i*/; i < 10;
i++ /*incrementing i by one*/)
{ //the start of the body of the forloop
println/*prints the following string*/
(/*here comes the string!*/"Hello, World!"/*that was the string!*/);
} //the end of the body of forloop
Decomposition
The general idea is the following: if a block of code performs a specific solitary function. These numbers are not meant to be taken verbatim; always use your judgement.
Someone who’s never seen any code before should be able to figure out your program's algorithm merely from looking at your run() function. Good function naming also plays a role, here, too, obviously, but the main point is about decomposition.
Good:
bool IsCoordValid(int row, int col, int maxRows, int maxCols) {
return ((row >= 0) && (row < maxRows) && (col >= 0) && (col <
maxCols));
Bad:
int Zero() {
return 0;
}
Whitespace
Inside a function, statements which form logical actions should be grouped together with adequate space to set it apart from the rest of the code. Variable declarations should also be set apart.
There's another kind of whitespace that's important, horizontal whitespace:
/* many terms with no spaces: never do this */
int i=2*i+12/i;
/* spaces around every operator: good */
int i = 2 * i + 12 / i;
/* using parentheses for readability and grouping: the best */
int i = (2 * i) + (12 / i);
Instance vs. Local Variables
It can be tempting to make everything an instance variable, once you've used them a few times. You should use as few instance variables as possible. Constants, on the other hand, are usually declared outside of functions (and hence have the same scope as instance variables).
Always Use Constants:
Our code should never contain “magic numbers,” meaning numbers we use in our code that don’t have a clear meaning. For example don't just have “7,” say DAYS_IN_WEEK. Instead of “10,” we write EYE_RADIUS. Well-named constants make it clear what the purpose of the variable is, and also reduce errors. If someone wants to change the EYE_RADIUS, they can modify its value everywhere in the program by only changing it once. If we just wrote “10,” they would have to go searching through the code to find all the places we use this value. The only numbers we don't need to turn into constants are the numbers 0,1 and sometimes 2.
General and Reusable Methods:
It is important to write methods that are general and reusable. If you find yourself copying and pasting code, this is probably a sign that you should have a more general method to accomplish this task. However, figuring out how to write general and reusable methods is an art, and is quite challenging. Look for similarities in your code, or ask yourself how you can use parameters.
There Are Many Ways To Solve the Same Problem:
As you can see by the RobotFace.java solutions included here, there are many ways to decompose the same problem. When you write your own programs try and consider the many ways to solve the problem, and the trade-offs and benefits of each solution.
Short Methods
We could have written our whole program in the run method, but it is not good style and is difficult to follow. Try and break it down into methods that are small, understandable pieces of code, and accomplish one main task.
Contributors:
bgwines
jkeeshin
Further Reference:
http://www.objectmentor.com/resources/articles/Naming.pdf
http://www.cs.arizona.edu/~mccann/style_c.html
Are you an SL who would like to contribute or improve this document? Email [email protected]