Comments on CIS 211 Labs 2 and 3, Spring 2000

General Comments

Coding Conventions, Styles, and Software Engineering Tips

Comments Specific to Labs 2 and 3

General Comments

• This applies to all work in the CIS department: if you didn't write it, say so. There are certainly cases when it is OK to use code that you have found somewhere rather than write it yourself. (Usually, of course, it is not OK to use code from other students.) However, you must always give credit to your source: say where you got it from. Using code, or analysis, without giving credit is plagiarism, and will be treated as such. The penalties can include anything from a 0 on the assignment to being expelled from the University of Oregon. If you have questions about what is OK, talk to either of the GTFs or to Professor Sabry.

  Coding Conventions, Styles, and Software Engineering Tips

• The Java compiler checks to see whether you have initialized a variable before you use it. This can be a useful tool to help you debug your code. However, if you initialize a variable to a bogus value, forget to initialize it "for real" before you use it, and therefore end up accidentally using the bogus value, you have shot yourself in the foot. Don't initialize variables to have meaningless values.

• Consider using this.fieldname to refer to fieldname inside the class definition. Sometimes it can make things clearer.

• Comments, comments, comments. If you put in words what your code does, you'll understand it better yourself, both now and later. Think about it this way: suppose that, at the beginning of this term, I had given you the code for lab 3. What comments would you have wanted there to be in my code so that you could understand both what it was doing and how?

• You should create a variable when it helps to clarify your code. A good rule is that you usually don't need to create a variable to hold the value of an expression unless you will use that value more than once. Thus, instead of

  Word wresult = new Word(w1 + w2);
  return wresult;
  

  it would be cleaner to write it this way:

  return new Word(w1 + w2);
  

  On the other hand, you should create a variable when you are going to use that value at least three times, especially if calculating that value is expensive. (You don't want to calculate cos(sec(tan(sin(3.14159)))) several times over if you can avoid it.)

• Don't redo work. If you have the same method, implemented the same way, in all subclasses of a class A, implement it in the definition of class A. If you've implemented a method in class A, and it doesn't work differently in its subclass B, don't reimplement it.

• Generally speaking, the classes that you're writing should not print diagnostic information to the screen. It's better to design the class such that the driver can get any information that it needs to from querying the class.

  An example: in lab 3, it is useful for testing purposes to know whether you've fetched something from the cache or whether you had to go to main memory. This is a borderline case in which diagnostic messages inside the code is more reasonable. However, you can also create a public flag inCache that is set to true if you got the data from the cache and false if you had to get it from main memory. The driver could then (at its option) examine this flag and print the appropriate message after fetch() returns.

• Don't separate definitions of variables from the place where you use them by too much code. This tends to lead to hard-to-trace bugs. For example: defining x=10, y=20 on line 5, setting z=x+y on line 50, and putting System.out.println("10 + 20 = " + z) on line 90 is a bad idea. (Using System.out.println(x + " + " + y + " = " + (x+y)) is less error prone in any case.)

• Don't use "magic numbers". If you need a constant value, declare it once and then use that instead. Using "magic numbers" (constant values such as "10" and "3.43") inside your code is asking for trouble, and is harder to change later.

• A cosmetic comment: it's best to hand in only source code; put your documentation, name, etc. inside /* comments */ or as // comments. Sometimes it's hard to tell which is the source code and which is the extraneous material.

  Comments Specific to Labs 2 and 3

• When you design an ALU, or anything that does arithmetic on Words of limited size, think about what should happen if your number gets too big (or small). For example, if your Words have 8 bits, and can represent negative numbers (so your range is, say, -128 to 127), what should be the result of inc(Word(127));? What should be the result of dec(Word(-128));? Should they "wrap around"? Should they "stick" at the max and min values? Should you throw an exception? Should you increase the size of the Word? There are several possibilities, although some may make more sense than others.

  Whatever you decide, you need to document your decision. Someone reading over your code should be able to see that you have considered these issues and resolved them.

  On a related note, many of you did not think about how negative numbers should be represented (especially those who used strings or arrays of booleans to represent words). These are the kinds of issues that you need to consider.

• Encapsulation: there are several comments here.
  • Don't write Word so that other classes have to know what its internal representation is. This implies that if you want to do integer arithmetic on Words, you should have a toInteger() method. The ALU shouldn't have to convert your Word from a string to an integer. You should even have a toInteger method if you implemented Word as an int, just because that way no one has to know that you implemented Word as an int in order to be able to use it.
  • The GT, LT, EQ flags should be private to the ALU class.
  • The internal representation of a Word should be private or protected (depending on whether you intend to extend Word or not).

  In general, don't make a field or a method public unless other classes need to be able to access it.

• The most common problem on lab 3: making CachedMemory a subclass of Memory, and then creating an instance of Memory inside CachedMemory. You can do either one, but not both: if you do both, then you have three storage areas--the cache and two main memories.

  Remember that, if CachedMemory extends Memory, that anything that is in Memory is also part of a CachedMemory. This means that to get main memory, you should call super(main_memory_size) inside CachedMemory's constructor.

  The only time that it makes sense to create an instance of Memory inside CachedMemory is if CachedMemory does not extend Memory.

  On a related note: it makes even less sense to reimplement Memory from scratch inside CachedMemory. Use the code we give you!

• Your cache and main memory should never be the same size. Think about what a cache is for: if it's the same size as (or bigger than!) the main memory, then it's useless.

  On a related note, you should be able to specify the size of both the cache and the main memory in the constructor.

• When you are implementing fetch(), you should not fetch data from main memory twice (one when you return the data, and once when you store it in the cache, for example). Remember that we're trying to simulate a real cached memory system, and fetching the same piece of data from the cache twice in a row is exactly the sort of inefficiency that caches were designed to reduce in the first place. Fetching the data into the cache and then returning the data from the cache makes more sense.