Programming style for CSC270

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 for C++):

1. All C programs must use Standard ("ANSI/ISO") C. "Traditional" ("K&R") C is forbidden where it conflicts with Standard C, as are compiler-specific extensions. Most compilers have an option to complie code in "ANSI compatibility mode", which means they will produce error or warning messages if you try to use constructs which aren't part of Standard C. In GCC, you can enable ANSI conformance with the -ansi and -pedantic flags. It's also a good idea to use the -Wall flag, which will do extra checking for errors of the "this-is-technically-correct-but-you-almost-certainly-didn't-mean-to-do-it" variety. So in summary, always compile your programs like so:

   	gcc -Wall -ansi -pedantic myprogram.c
   	

2. You must have a comment header at the top of each file which lists the file name, your name, your student number, and a short description of the file.

3. All functions (except main()) must have prototypes.

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 also that the comment should not describe the implementation of the function unless that is an unavoidable part of specifying the interface.

5. 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. The marker 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.

6. "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.

7. Specifically, you should not use 0 and 1 to indicate "true" and "false". Instead, set up some appropriate macro definitions, such as:

   	typedef int bool;
   	#define TRUE 1
   	#define FALSE 0
   

8. Your programs must be "indented" ("paragraphed") to help the marker read them. Most good editors and IDEs support auto-indenting; you are strongly encouraged to learn how to use one. As a last resort, you can always do it by hand, or experiment with the Unix cb ("C beautifier") command.

   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.

9. 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. */