Notes for C programmers
The most important comments are those at the beginning or in a separate file.
They should include
Major functions/methods should have comments at the beginning. It is very useful
to give PRE- and POST-conditions for the function. For example, a binary_search
may have a pre-condition that the array be sorted and a post-condition that
the return value is the location the key was found in or -1 if the key
was not found.
- identification of the programmer(s) (and who gave help)
- purpose of the program (what it does)
- example(s) of how to use it.
- URL for more information -e.g.: http://www.cs.dal.ca/~sedgwick/2132/a1
Always indent your code in a systematic way.
There is a utility called indent which can be used to fix to spacing
of a badly formattted C file.
E.g.: indent -br *.c
This utility has many other options. Another utility is indent-e which works
for C++ and Java and other languages as well.
C comments have the form /* --- */.
Virtually all C compilers now accept the C++ style beginning with //
and extending to the end of a line. You may use these in Dr Sedgwick's classes.
Format your programs so that they read well when printed on ordinary paper.
Usually this means lines should not be longer than 80 characters.
This means that people can read your programs on small screens.
Note that 65 characters width is a common limit for documentation.
- Store only one program or project in a given directory.
Use stderr (cerr, System.err) for error messages.
Output to stdout (cout, System.out) may be redirected and not noticed.
Do not use the #include mechanism to include .c files or complete c functions.
Header files should contain a one-line prototype for each function
but not the body of the functions.
Do not include header files which your program does not use.
Some systems allow you to omit common header files like stdio.h or stdlib.h.
Do include these if you use features from them so that your program will work on other systems.
- Do not "hard-code" constants in your functions. Define them where they may
be easily changed.
- Do not use global variables. Instead pass parameters.
Some older C functions are no longer recommended. For example, gets()
reads a line but does not check that the line is too long. Use fgets()
instead. Other C functions depend on the use of static variables which
will not work in multi-threaded applications. This is a problem with the
string-tokenizer strtok(), for example. Use the newer function strtok_r()
instead. These functions are sais to be "re-entrant".
Compile your programs with the -g option:
gcc -g a1.c
This adds a global symbol table to your program for use when debugging.
It also works with javac and g++ (C++).
Learn to use a better editor than pico.
These editors let you move to a given line or replace all occurences of one string or pattern with another.
References are widely available including in "/doc/" on borg.
- vim is a version of vi
available on our unix systems and also free for home use. gvim is the graphical menu oriented version.
- emacs and a xemacs have many features to make programmers more productive.
Learn to use the debugger gdb or ddd. See text reference or
/doc/gdb-guide.ps on borg
or example 1,
or example 2,
or example 3.
Use the man program to review the documentation of standard functions. E.g.:
The problem is that you need to know the name of the function first.
The following are some reference web sites:
If you find other good web site for C please inform your instructor.
Suggestions to improve these guidelines are welcome.