Writing Better Code

Write Readable Code

In your programming assignments, you are expected to write well-documented, readable code. There are a variety of reasons to strive for clear and readable code. Since you will be working in pairs, it will be important for you to be able to read your partner's code. Also, since you will be working on OS/161 for the entire semester, you may need to read and understand code that you wrote several months earlier. Finally, clear, well-commented code makes your TAs happy!

There is no single right way to organize and document your code. It is not our intent to dictate a particular coding style for this class. The best way to learn about writing readable code is to read other people's code. Read the OS/161 code, read your partner's code, read the source code of some freely available operating system. When you read someone else's code, note what you like and what you don't like. Pay close attention to the lines of comments which most clearly and efficiently explain what is going on. When you write code yourself, keep these observations in mind.

Please clearly indicate the code you have added to OS/161 by enclosing it with comments such as:

    // BEGIN GROUP XX's A2 SOLN

    /* Your actual code here, along with descriptive comments */

    // END GROUP XX's A2 SOLN

In simple cases, such as adding or changing a single line of code in an existing function, just place the comment at the end of the line.

Here Are Some General Tips For Writing Better Code:

• Group related items together, whether they are variable declarations, lines of code, or functions.
• Use descriptive names for variables and procedures. Be consistent with this throughout the program.
• Comments should describe the programmer's intent, not the actual mechanics of the code. A comment which says "Find a free disk block" is much more informative than one that says "Find first non-zero element of array."
• Pay attention to compiler warnings! The C programming language will allow all sorts of poor practices. The compiler can't reject these things as errors, but they are usually a sign that you are doing something you should not. Do not just arbitrarily "cast" variables to the right type to eliminate warnings - make sure you understand why a particular type of variable is needed, and that casting makes sense in that situation. It may seem that casting causes "weird" things to happen, but they are all consequences of the C language and the internal representation of different data types. Here are some interesting examples of the behavior of C programs when signed integers are represented using two's-complement (although this is the most common representation today, others are possible, and the resulting behavior may be different):
  • In comparisons between signed and unsigned types, C implicitly casts the signed variable to an unsigned value, and then does the comparison assuming both values are non-negative. If you see a warning like "warning: comparison between signed and unsigned", you should be very cautious. For an example of what this can do, look at sign_unsign.c. The result may be surprising if you aren't aware that -1 was converted to an unsigned value prior to the comparison.
  • Casting from a smaller integer type to a larger integer type (e.g. char to int - note that "char" is really a single-byte integer type, it does not have to store ASCII character values) causes the "extra" bits in the larger type to be filled by replicating the most-significant-bit (also known as the sign bit) of the smaller type. Remember also that integer types in C are signed by default. Consider the program diff_size.c. What do you expect will be printed?
  • Casting from a larger integer type to a smaller integer type causes the smaller type to be filled with the contents of the least significant bytes of the larger type (independent of the byte-ordering of the machine).
  • Casts between ints and floats are unlikely to cause trouble in this class, since most OS code does not work with floating point values.