This is a program hygiene and best practices guide for CS314. It contains a list of rules we expect you to meet for the code you turn in for programming assignments. This page covers the entire semester, so it is not meant to be something that you memorize and understand entirely through one read through. Rather, it is a reference guide that you will be able to use to look up rules and examples.
Note that this guide is not 100% comprehensive. A guide that tried to cover every particular issue would be ten times the size of this one. There may be specific things on each assignment we are looking for and the TAs and other graders may find issues not covered by this guide. If so they will provide feedback so you can improve the code you write.
"The cleaner and nicer the program, the faster it's going to run. And if it doesn't, it'll be easy to make it fast." - Joshua Bloch
"Code is read more often than it is written. Code should always be written in a way that promotes readability." - Guido van Rossum
"
Why does the internal structure of a program matter?
A program is externally correct, if it produces the correct results for valid inputs. Many people believe that when writing code, the only thing that matters is if your code is working or not. This is false - while it's important to get your code working, it is just as important to make sure your code is understandable by other people.
Programming is a highly collaborative activity - it's fairly common to have to work together with other people, sometimes even hundreds of them at a time. As a result, it's very important to write code that is easy to work with to allow others to integrate seamlessly with your work. Another benefit is that since clean code is easier to understand, you'll work much faster and introduce fewer bugs.
All programming assignments in CS312 and most in CS314 are done individually. However, it is still important to write readable code that follows our course hygiene guidelines - it's the core difference between whether a program is pleasant or impossible to work with.
In general, focusing on writing clean code forces you to acquire an eye for detail. The same holds true when writing an English paper or a Chemistry lab report. Programming, and writing correct (externally and internally) programs requires careful attention, so it's better to acquire that habit sooner, rather then later. As a programmer you have a responsibility to write as clean and well-designed code as possible to minimize the chances of bugs and accidents that might sneak in due to carelessness. The sooner you can get into the habit of caring about detail and correctness, the better.
Note, these are our guidelines for Mike Scott's CS314 sections. They will differ from other style guides. It does not mean one is right and one is wrong. In some cases it is simply a matter of preference. That said, we expect you to follow these guidelines in CS314.
Although most of these are covered later, these are some of the easiest to spot items and therefore the ones that are most often lead to points lost on assignments.
Typically any literal int in a program has some meaning. While that meaning may be clear and obvious when you write the code, it will not be clear and obvious to someone else looking at your code later, including your future self.
Therefore for any literal ints besides -1, 0, 1, and 2, create and use a constant.
Example. Count the number of Strings in array of Strings that have a length greater than or equal to 5.
final int MIN_LENGTH = 5;}
int count = 0;
for (String s : data) {
if (s.length() >= MIN_LENGTH) {
count++;
}
A method that is more than 25 lines of code is likely trying to do too much or has redundant code. Break longer methods up into smaller methods to provide structure and / or remove redundancy. Better yet, try to devise a simpler solution.
Don't declare variables until you need them. This helps reduce the cognitive load of trying to understand code. Following this guideline solves so many other issues such as minimizing the number of parameters to a method, minimizing the number of instance variables for a class, and not using static variables as a form of global variables.
i, j, and k are fine for loop control variables when there is no other meaning attached to the variable, but in general we want to name our classes, methods, variables, and constants based on what they store or do.
Yes, you must comment your code, but read the page on proper commenting. Not too much, not too little, just right. Don't simply repeat what the code is doing. Provide a higher level explanation of the method and / or algorithm. If you follow the other guidelines much of the code becomes self commented and you must only explain complex or unusual aspects of your code. Of course every method shall be commented.