Notes for C programmers

 

1. Comments: The most important comments are those at the beginning or in a separate file. They should include
   • 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
   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.
2. 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.
3. 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.
4. 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.
5. Store only one program or project in a given directory.
6. Use stderr (cerr, System.err) for error messages. Output to stdout (cout, System.out) may be redirected and not noticed.
7. 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.
8. 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.
9. Do not "hard-code" constants in your functions. Define them where they may be easily changed.
10. Do not use global variables. Instead pass parameters.
11. 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".
12. 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++).
13. Learn to use a better editor than pico.
    1. vim is a version of vi available on our unix systems and also free for home use. gvim is the graphical menu oriented version.
    2. emacs and a xemacs have many features to make programmers more productive.
    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.
14. 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.:

        man fgets
        man strtok_r
    

    The problem is that you need to know the name of the function first.
15. The following are some reference web sites:
    • Kirk MacDonald found:How to write Unmaintainable code.
    • http://www.infosys.utas.edu.au/info/documentation/C/CStdLib.html
    • http://www.linuxgazette.com/issue24/rogers.html
    • http://css.engineering.uiowa.edu/~cie/WebLectureFunctions/
    • http://www.eecs.harvard.edu/~vino/
    • http://www-ccs.ucsd.edu/c/
    • http://www.cs.cf.ac.uk/Dave/C/
    • http://members.aol.com/wantondeb/"
    • http://www.visac.uq.edu.au/people/kjones/ph361/cnotes/
    • GCC C99 status
    • C99 changes
    • C99
    If you find other good web site for C please inform your instructor. Suggestions to improve these guidelines are welcome.