Comments on CIS 211 Lab 1, Spring 2000

General Comments

Coding Conventions, Styles, and Software Engineering Tips

Lab 1-specific Comments

General Comments

• First and foremost: everybody got lots of green ink--in the form of comments--all over their papers. Don't feel embarrassed--learn from it. Many of these comments don't translate to lost points--this time.

• Mostly people did reasonably well. Some didn't do so well. However, there were a few people in each lab that didn't turn in an assignment at all, and their grades were pretty bad. :( The labs exist to give you an opportunity to learn what you need to know to pass the class--take advantage of this opportunity, and do the labs. It's also worth noting that the labs build on one another, so if you fail to do one, the next lab will be more difficult.

• Generally speaking, no late assignments will be accepted.

  Coding Conventions, Styles, and Software Engineering Tips

• Please use a consistent style. Some of the submissions were very hard to read because they either didn't indent things that they should have indented, or did so in an inconsistent manner. Examples of good style can be found in the Java textbook for the course. Another style (which I happen to prefer) is as follows:

  public class wugga
  {
      String nonsense;
  
      public void wugga(int dooba, int thibbeh) throws A_Fit
      {
          int i;
  
          for (i = 0; i < dooba; i++)
          {
  	    if (test(dooba) < 7)
              {
                  do_something(thibbeh);
              }
              else
              {
  	        repossess_car();
  	        throw A_Fit;
  	    }
  
  	    toast_cpu(i*70);
          }
      }
      
      String get_nonsense()
      {
          return this.nonsense;
      }
  }
  

  There are a number of things going on here stylistically (spacing on a line, indentation, placement of brackets, etc.) but they all add up to one thing: improving readability. Make it easy to tell where a set of statements begins and ends. Use blank lines to separate blocks of code that aren't directly related--don't worry about the "wasted" space inside your code. For more examples of, and details on, good style, see the style guide on the CIS 210 web page. This style is a bit different from the one I have specified here, but is perfectly acceptable. (The major difference is that I prefer to put opening brackets '{' on a line by themselves; otherwise they're harder to find and match with the corresponding closing brackets '}'.)

• On a related note, you don't help readability by handing in a page with three lines of code on it. If you have a bunch of small related methods, put them all on one page.

• Don't leave in dead code (code that you've commented out), especially if you only needed it for development and verification. It's confusing and makes the rest of the code less clear.

• Use descriptive variable names. You've all heard this one.

• Don't enclose unrelated class definitions together in the same wrapper class. As a special case of this, generally you should not put driver code inside the class which the driver is to test. Think modularity and encapsulation.

• Don't put more than 75 characters on a line, and in general make sure that the lines on your printout neither wrap around, nor get cut off by the edge of the paper.

• Don't specify driver data inside your program code. If you do, you have to recompile the driver each time you want to test new data. There are two basic alternatives for specifying data:
  • Put the data on the command line. This is perhaps easiest (at least in Java).
  • Get the data interactively from the user. This is a bit more complicated, but doesn't require the user to remember your command-line syntax.
  In both cases, you may wish to specify an input file rather than a list of parameters, if your program requires several pieces of data.

• Don't reinvent the wheel. A few people implemented And, Or, Not, and OneBitComparator twice: once as we asked them to, and again inside the driver which actually compared two integers. This is silly, and bad software engineering practice. Don't waste your time reimplementing something that you've already coded.

• The cardinal rule of software engineering: write it so that you, or someone who knows as much as you do now, will be able to understand what your code does when you look at it again three years from now. Put comments in as necessary, structure your code visually so that it's easy to read, and generally get out of the habit of writing quick and dirty code. It will save you time in the long run, especially when you start debugging and doing code maintenance.

• Your code should always do something sensible with legal inputs. This has many implications. A specific example of this error that several students made on Lab 1 was that, in Part II, they dealt only with integers of limited size (up to 8 bits, for example). The specification pretty clearly implied that any integer might be an input to your comparison routine--not just integers no bigger than 255. A couple of people noted their program's limitation in their comments; this meant they lost fewer points. The ideal solution was to handle all legal inputs, i.e., any integer accepted by Java's string-to-integer parser. A somewhat less acceptable solution (in this case) would have been to throw an exception on inputs that were outside the expected range. (Sometimes throwing an exception is actually a better solution; it depends on the application.) Still less acceptable: mentioning the limitation in your comments. Not acceptable: failing to acknowledge the limitation at all. The ability to gracefully and handle any legal input is a key component of program robustness.

  A corollary: don't treat illegal input as if it were legal. An example of this might be as follows: suppose that you have subclassed Word into Data and Instructions. Incrementing an Instruction doesn't make any sense. However, simply returning the Word which is the Instruction itself doesn't make any sense either. A C programmer would write the inc() method so that it would return an error value, or set an error flag, if it were passed an Instruction. As Java programmers, you should use the Java mechanisms for handling problems, and throw an exception in this case.

• Unless we specify otherwise, you must always supply at least a minimal test driver that exercises the classes that you have been asked to implement. You should also supply a printout of the output of running this test driver.

  Lab 1-specific Comments

• There are several ways that you could have implemented logic gates. Generally, each has advantages and disadvantages. I won't give all possibilities, but I will list a few major ones.
  1. UnaryGate and BinaryGate have internal state in the form of one (or two) input variables which are set by an input() method, and in the form of a single input variable which is returned by an output() method. Both UG and BG have abstract methods for either input() or output() (the logic for evaluating the inputs has to be in one of them) which are implemented in the And, Or, and Not classes. The output() method, being maximally generic, may be specified in the Gate class.
  2. UnaryGate and BinaryGate have no internal state, and simply specify abstract methods (implemented in the And, Or, and Not classes) for evaluating the inputs. In this case the And, Or, and Not classes are essentially just wrappers for their evaluation methods.
  3. Similar to 2, but the methods are declared as static in the And, Or, and Not classes, so one does not have to create an instantiation of the class in order to use its method. This is perhaps the most purely mathematical implementation, and corresponds to the implementation of some of the methods in the Math package.
  Within each of these, you could use the &&, ||, and ! operators, or test against specific values. There are two pitfalls that students tended to fall into when making the choices of operators to use to evaluate the gates:
  • Using ints rather than booleans. This is not a bug per se, but if you use ints, you have to be more careful. Everyone believes that 0 is false and 1 is true. But what's 17? -6? There is a convention in most programming languages that 0 evaluates to 'false', and any nonzero value evaluates to 'true'. You can choose to throw an exception if you are given a value that is neither 0 nor 1, but a number of students ignored this issue entirely. Using booleans means never having to throw an exception (when implementing logic gates, anyway). :)
  • Using multiplication and addition to implement AND and OR. The people who did this should be commended for their recognition of the connection between the mathematical operation '*' and the logical operation '&' (and the corresponding connection between '+' and '|'). However, everyone who did this also failed to consider the effect of handling negative numbers, and lost some points for this. The other reason not to do this--aside from the additional complication of having to consider negative numbers--is that on real machines, multiplication and addition are more computationally expensive than AND and OR, so it doesn't generally make sense to implement AND and OR using multiplication and addition. (Usually you build multiplying and adding circuits out of AND and OR gates rather than the other way around.)

• Don't use a single constructor for both Unary and Binary gates, if you are using the constructor to specify the input value(s). The two types of gates have different numbers of inputs, and trying to combine the two types of constructors just leads to confusing and/or unnecessarily complex code.

• Use the '<<' and '>>(>)' operators when you're multiplying integers by 2ⁿ or 2^-n. They are faster and sometimes more accurate than the Math.pow() method. See the Java documentation for their use.

• Be careful, when comparing two items bit by bit, not to simply take the result of the last bitwise comparison as the answer for the entire problem.

Keep these comments in mind for future projects. There's a lot here, but at least it's all in one place. :)