[cs631apue] midterm grading

[Jan Schaumann]

Hello,

I've just sent out grades for the midterm.  If you have not received an
email from me with your grades, please let me know ASAP.

All in all, most of you did fairly well in the assignment.  The
following are things that are worth noting out because several of you
had problems with them:

- check the return code of all functions; THAT INCLUDES MALLOC(3)

  Many of you have invoke functions and use their return value without
  checking it for validity.  This covers malloc(3) -- which, I can
  assure you, can and will fail -- as well as functions like
  getpwnam(3) or getenv(3).

  If a function _can_ return NULL (or any other value undesirable for
  you to use), then, at some point, it _will_, and your program will
  misbehave.

  Any program that crashes, aborts unexpectedly, dumps core or otherwise
  misbehaves spectacularly as a result immediately drops a full grade.


- do not duplicate code

  If you have the same block of code even twice, factor it out into a
  separate function.


- use multiple source files

  Keeping all functionality in a single file makes it hard to maintain
  and makes it easier for you to abuse non-modular structures.

  Make sure you understand how the compiler works and how make(1) can
  help you.  Tomorrow's lecture will cover some useful ground here.


- return a meaningful error code

  When you encounter an error, do not exit with an exit value of 0.


- do not abort on all error conditions

  When the user invokes your command, they have certain expectations
  about how it will behave.  Just because you can't read on subdirectory
  does not mean you should abort listing the contents of all other
  directories, for example.


- lexicographic sorting should not treat upper-case letters as if they
  were lower-case letters

  Sorting strings lexicographically looks at the ascii value of the
  characters;  upper-case characters come first, then lower-case
  characters.

  Sometimes you may encounter tools that appear to sort names as if they
  used strcasecmp(3); this is usually a false assumption.  Instead,
  these tools might use strcoll(3) to allow the sorting of
  locale-dependent characters in the expected order.  If you used
  strcoll(3), doing so would be fine, as the user can manipulate that
  behaviour via the LC_COLLATE environment variable.  Simply
  lower-casing all strings before sorting is _not_ a solution.


- do not implement features that are not asked for

  Some of you chose to implement color coding of directory entries.
  This introduces complexity, requires you to write unnecessary code and
  increases the number of bugs in your program.  What's more, you're
  unlikely to get it right:  color-coding requires escape-sequences,
  that are undesirable under certain circumstances.  For starters, you
  need to turn off color-coding when output does not go to a terminal.
  Next you need to make sure that the terminal in question can interpret
  the escpae sequences.  You also need to allow the user a way to either
  turn off color-coding and/or to change the colors -- whatever colors
  you picked may simply not be a good choice for the user's terminal.
  (Consider a terminal that has a light background, and you chose to
  color-code certain entries with yellow or another light color.)
  Different users have different color-related disabilities and tools
  relying on mechanical interpretation of the output can break.


- don't trust the environment

  This goes hand-in-hand with the advice to check the return code of any
  function call you make, but if you're getting any information from the
  environment, then that may include completely bogus values.  If you
  interpret the value of an environment variable as a number, be careful
  not to divide by zero if the value is 0 or cannot be converted into a
  number.  (BLOCKSIZE=bacon, for example.)


- stress test your tool

  Make sure to test it not with the most common input, but with the edge
  cases.  How large can a filename be?  How large can a file be?  How
  large can a file hierarchy be?  If your instructor tells you in class
  that "ls -lR /" will be a sample invocation, make sure your program
  can handle that.


- have a consistent coding style

  Do not mix spaces and tabs, do not mix different styles of placement
  of braces.  Use a text editor that can show you deviations and don't
  copy and paste code from other sources retaining their particular
  coding style.


- don't copy code into your submission which you do not understand

  Finding a solution for what you think might be your problem on the
  internet and pasting it into your work without understanding it is not
  a good idea.  This is usually obvious and particularly unfortunate
  when it actually addresses a platform specific issue that you do not
  even encounter in your code.


Here are a few of the tests you would want your midterm solution to
pass: http://www.cs.stevens.edu/~jschauma/631/ls-test  (This is not an
exhaustive test, but a good start.)


Congratulations on finishing this project -- I know it was a lot of work
and I hope you have learned a lot and can be proud of your code.

-Jan