CSC270H1Y - Summer 2001

All programs must be written in C or C++ as directed.

A programming style

A software organization usually requires all its highly individual programmers to follow a "house style" — a set of standards enforced as part of the process ensuring successful software production. The programmers have their own strongly-held views on programming style, but they are required to conform to the house style in work they do for the organization.

In this course we will not set many rigid requirements, but we do have a minimal house style for assignments written in C (with some obvious extensions to C++):

1. All C programs must use Standard ("ANSI") C. "Traditional C" is forbidden where it conflicts with Standard C. In case of doubt, the compiler gcc will decide for us: if you get no errors or warnings by compiling with

   	gcc -Wall -ansi prog.c
   

   then we will consider that your program follows the Standard C rules (even though many programmers use more of gcc’s flags than this). Therefore, it makes sense to compile at least once with gcc even if you do most of your development at home.

2. You must have a comment at the top of each file which lists the file name, your name, your student number, your section (Day or Evening), your tutor's name, and a short description of the file.

3. All functions (except main) must have prototypes, even if the prototype immediately precedes the function definition.

4. All function definitions (except main) must be preceded by an explanatory comment stating completely but concisely the purpose of the function, including the role of all arguments. Note that this comment must come immediately before the function header, not after. Note also that the comment does not describe the implementation of the function unless that is an unavoidable part of specifying the interface.

5. The main() function must be in one of the two standard forms: int main (void); or int main (int argc, char** argv);

6. Global variables are nearly forbidden. "Nearly forbidden" means that you may only use a global variable if you write a comment justifying its use next to the declaration that defines it. Your tutor may reject the explanation; if so, you will be considered to have broken the rule.

   Any variable declared outside a function is a global variable, even if there are several source files and the variable is used in only one of them. Generally speaking, communication between functions should be by passing parameters, not by shared access to global variables.

7. "Magic numbers" are forbidden. Use #define to give names to constants.

   Exceptions are: zero, which can be used as a success or failure return value from functions; the null character '\0'; and small integers such as 0, 1, or 2 when the algorithm being used naturally requires these numbers. For example, in binary search 2 must naturally appear, and

          for (i = numnodes - 1; i >= 0; i = i - 1)
   

   looks strange indeed with names for 1 and 0.

8. Specifically, you may not use 0 and 1 to indicate "true" and "false". Instead, set up these definitions:

   	typedef int bool;
   	#define true 1
   	#define false 0
   

   These are not the conventional C definitions, but they allow us to write programs using the same notation as in C++, so we should get used to them.

9. Your programs must be "indented" ("paragraphed") to help the marker read them. On Unix, use cb or indent, or do it by hand. On a PC, use a good IDE or an editor such as vim that supports auto-indenting.

   Indenting, whether automatic or done by hand, can be tricky to get right when someone else is viewing the results with a different display program. Read "How to prepare your assignments for submission" for some advice.

10. Comments are essential, but it is very hard to give rules that specify exactly what is a good comment. In an academic course, a general rule is very easy to give: remember that you are trying to help the marker read your code. Both omitting comments and including too many comments can be undesirable. Assume that the marker is a programmer but does not know what you're thinking.

    A few pointers:

    • Make your comments precise, thorough and brief. An overlong comment is worse than a correct short one.
    • Don't restate the code. Explain what you were thinking when you wrote it.
    • Use comments to define your variables. Even a loop variable can be commented usefully:

      	int i;  /* loop counter*/
      

      or perhaps:

      	int i;  /* counter through list elements */
      

    • Use comments to state what you're about to do:

      	/* Read the input. */
      

    • Use comments to say what you've achieved:

      	/* The list elements are now in alphabetic order. */
      

11. When a program requires the definition of a data type or a class, each type or class should be implemented in its own .c or .cc file, with an interface specified in a .h file.

Handing in your work

The goal of your submissions is the same as in previous courses: to persuade the marker that your programs do the right thing. And as always, a sensible approach is to make the marker’s job as easy as possible.

Details of how to submit your work are given in "How to prepare your assignments for submission". Here, we'll just note the major points:

• Electronically, hand in your source files -- the files containing your program code. This includes both .c and .h files.
• On paper, hand in printouts of your test data files and of the corresponding output. Label them clearly using a pencil or pen. It may be obvious to you what a test run means, but it’s not to anyone else.
• Any required report should also be handed in on paper.

Click here to go back to the menu, if your browser does not support frames.