Project Requirements

by: burt rosenberg
at: august 2019

These general remarks apply to how the do the projects for csc421. Please abide carefully.

• Platform —
  • Projects are programming projects, done in C on Unix.
  • All reasonable effort shall be made to make your code platform independent, however your code must work on Ubuntu Xenial Xerus.
  • For csc421, Operating systems, use ubuntu-16.04.6-server-i386.iso.
  
  
• Subversion —
  • You will share and submit your projects using the departmental subversion site, svn.cs.miami.edu.
  • Please refer to my subversion tutorial and the Subversion red book for information about subversion.
  
  
• Makefiles —
  • You will use Makefiles so that the graders and assistants can build your projects from source, and are guided through your test suites.
  
  
• Test —
  • Thou shalt make test suites for your code.
  • Thou shalt sayth not "my project works". Thou shalt sayth "when the test suite is run, the expected behavior is observed."
  
  
• Coding style —
  • Thou shalt write ANSI C.
  • Your name and date must be in comments at the top of all files. I consider this your promise to me that this is your own work, or you have explained the source of the code otherwise.
  • There are four important things about a C variable:
    1. It's name is not important (no introspection).
    2. It's type.
    3. It's scope.
    4. It's lifetime.
    And therefore:
    • Do not declare variables in the middle of a block. Reject this C99 feature. A variable's scope and lifetime should be a block, end of story. Coding is hard enough.
    • Do not use Variable Length Arrays (VLA). Reject this C99 feature. They turn sizeof from a keyword into a function call, sometimes, and you now have run-time type errors as well as run-time allocation errors. Coding is hard enough without turning your back on the compiler's assistance in memory layout and type computation.
  • The C++ // one-line comment style is ok. (Although it then distinguishes new-lines from other white-space.)
  • Comment what isn't obvious. Comment what confused you when you wrote this code.
  • Comment assumptions on parameters at the top of the function block.
  • Use only lower-case in filenames, with exceptions for strong historical precedence: Makefile, README.TXT, maybe a few others. Never distinguish a file by case, and always refer to the file by the chosen case.
  • Use header files. Consider them as declaring your API. What's in the .h file explains what you intend to be the stable functions and types, as opposed to helper functions that might change.
  • I prefer writing subroutines more basic first, so I don't need forward declarations. I consider this a huge hint to debuggers about what depends on what. I recommend not doing forward declarations unnecessarily.
  • I'm conflicted on the use of zero-length arrays. Harbison and Steele tells me I'm an outlaw, page 98 but I can't seem to care. Your choice.

This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

author: burton rosenberg
created: 21 aug 2017
update: 27 aug 2019