CS 246 - Systems Programming
Programming Design Guide
Now that you are no longer a new programmer, you are expected to pay attention to
your code organization. Your programming should adhere to the standards explained here.
While some of the rules are due to convention, many more are pearls of wisdom distilled
from solid software-engineering principles and all of them are essential for making your
code readable and/or easy to maintain and modify/reuse. This document explains guiding
principles. For more specific formatting rules please refer to the formatting guidelines.
- Every line of code should have a deliberate effect on your program. If you are not
sure why a line is there, it shouldn't be. If your program stops working because
you removed that line of code that you don’t understand, you need to understand
it before you put it back.
- Within a single program, do not copy-and-paste code, only to change a few details. Instead, declare a function parameterize it. Do copy and paste code (changing as needed) between programs.
- Use constants to avoid so-called magic numbers - numerical
values that are scattered all over your program and are difficult to understand or
- Do not debug by trying all combinations. If you (or the debugger) pinpointed a
line that doesn't work, it is important to spend the time to understand why. The
most valuable gain of programming proficiency happens right here. A bug is not
truly fixed unless you
- understood why it happend in the first place
- understood why changing the code the way you did fixed it
Scoping and Encapsulation
- Declare variables in the smallest scope possible. That is, prefer local variables over global variables.
- C does not have the class-like encapsulation of Java. Still you can be inspired by Java encapsulation and attempt to achieve similar ends.
In C global variables store the data and keep track of the states.
Thus it is very important to carefullly consider how to organize your functions and instance
variables so that they communicate well and verifiably. Generally it is easier to start writing a program with a ton of global variables. Generally having a ton on global variables make a program very difficult to debug.
To encourage you to avoid global variables, on each assignment I will (somewhat) arbitrarily decide how many instance variables to allow. In your programs, I will deduct one point for every instance variable that you use in excess of my limit. I will NOT normally announce the limit. Constants will not count as global variables (since that do not vary).
Data Structure Design
Often, there is more than one way to store and represent data.
- Do not store the same thing more than once, or in more than one place.
- Choose the smallest storage so that the above is true and accomplishes your