General Coding Issues for CSE 1320
Modified from Ray Springston's material for 1320, 1325, 3305, and 4301
This document contains various tips, suggestions and guidelines for formatting, compiling, running and debugging your C programs.  The document contains the following sections:

Formatting Guidelines

Program structure guidelines

Commenting guidelines

Compiler tips


Lab output

Script session editing Q and A

Formatting Guidelines
Matching block braces ({, }) should be formatted consistently.   One approach is to vertically align them.
Use only one instruction per line. 
One blank line should be used to separate declarations from instructions.
One space should be used to separate each operator and its operand(s). 
Every switch statement must have a default case. 
Instructions within the same block should line up vertically 
Avoid excessive use of tabbing 
Avoid wraparound code (usually due to excessive tabbing) 
Separate a line of code and it's line comment horizontally--code on the left, line comment on the right. 
Prompts should be brief and clear--specify exactly what is to be done by the user. 
It is not necessary end a loop with a comment, such as //end if--this was introduced when teaching the basics of programming, but should be left out now. 

Program structure guidelines
main( ) must be the driver function in the driver file for C programs ,  C++ programs and for applications in Java, because the language requires that execution begin with the function associated with that keyword; therefore, the top-level control of the flow of the program should be done in main( ).  main( ) therefore must do more than just call a function, but should not perform more than one overall responsibility (flow control). 
In general, each of the following responsibilities deserves its own function: 
                   --flow control (main) 
                   --explanation to the user, as to the purpose of the program 
                   --processing an input file 
                   --processing of a complex data structure 
                   --display of the results 
Do not hardcode numbers into the code--define them as constants and use the name of the constant instead of the number itself--this greatly simplifies maintenance of the program. 

Commenting guidelines
The purpose of a line comment is to explain a not-so-obvious line of code in terms of the assignment, not in terms of the language. 
The burden of explanation should be encapsulated in the meaningfulness of the identifier, not in a line comment used to explain a meaningless identifier.
For a program, each file should have its own header. Each function should also have its own header, even if the function is 'inlined' by the compiler.
An example function header would be: 
FUNCTION NAME :     calculateSum 
INPUTS :         a double A, and a double B 
RETURNS :    a double 
PURPOSE :     calculate and return A to the Bth power, recursively 
An example program header for a file would be: 
PROGRAMMER:       (your name) 
LANGUAGE:             C 
CLASS:                        CSE 1320-501, "Intermediate Programming in C", Fall 2002
PLATFORM:              OMEGA 
OS:                                UNIX 
COMPILER:                gcc
ASSIGNMENT:         (Homework #2, Lab #1, etc.)
ASSIGNED:               (date the assignment was assigned) 
DUE:                            (date the assignment is due) 
FILE NAME:               (name of this particular file, not of the program) 
FILES USED:              (one file name per line)
CONCEPTS:              (as stated in the assignment) 
WEIGHT:                    (as stated in the Class Policies) 
PURPOSE:                  (Define the main routine and functions for ...)

Compiler tips

In Unix gcc, you can use the -o option to specify the name of the executable file instead of a.out.

        $ gcc myprogram.c -o myprogram

This generates an executable program, myprogram in the same directory 1.



What can cause an "unaligned access..." compiler error?
                   ANSWER:  going beyond the bounds of an array
What can cause an "unsatisfied internal constraints..." compiler error?
                   ANSWER:  using a non-constant variable as the dimension of an array


Lab output

1320 students: include the following line in main(), after declaring any  variables:
                   printf("%s %d %s %s %s %s %s %s %s %c\n", "This is line number ",
                                                                                                             " of the file ",
                                                                                                             " which was\n compiled on ",
                                                                                                             __ DATE __,
                                                                                                             " at time ",
        Note that each identifier is an upper-case word with 2 underscore characters on each side of it. 
The script file must contain:
                   a. Source code (use 'cat' for each file) 
                   b. Any header files which the programmer coded and is using in this assignment 
                   c. Compile, etc. commands 
                   d. Output 
Be sure the script session shows exactly what you want it to show; if it does not, get another printout, rerun the script session, etc.
No control characters should show up in the script session 
Do not backspace or edit source code while in a script session. 
Do not turn in assignments from any printer that is not case sensitive.

NEVER put your Social Security Number and name together.

Script session editing Q and A

How can I get rid of the ^M's at the end of each line of the script session?

ANSWER 1: From the unix command prompt, assuming a file exists called "HW1.log", type the following:

                   rmcr HW1.log > HW1.log
ANSWER 2: From within the vi editor, while editing the associated file, type at the ':' command prompt:
        where the ^v and ^M are control characters.  ^v is for "remove all occurrences of the following control character", and ^M is the control character to be removed.  The ^v will only print a '^' symbol, and the ^M will only print the 'm' of the ^M.

ANSWER 3: So, to get rid of the ^D, which usually shows up when exiting out of the script session,
ANSWER 4: Using the emacs editor, while editing the associated file, type
                    M-x replace-regexp C-q C-m  C-q C-j 
ANSWER 5: Many editors will automatically remove these control characters simply by editing the file in that editor.  So, if the script session has been saved into a file which contains those control characters, just open that file in an editing session using that editor and then save it.  The control characters should no longer be in the file.
ANSWER 6: These control characters will often cause the printout to be double-spaced when using an older printer.
ANSWER 7: Whether these control characters appear during the editing session depends on the choice of editors.
Why does each line of my printout end with <^M>? 
ANSWER: The code was probably ported to OMEGA using 'telnet'. Use some other method, such as 'ftp', if porting from home, or bring a disk to campus   and use the facilities in Ransom Hall or Nedderman Hall to port the   code over to OMEGA. 

This page was last updated on 09.03.2002 by JCMTiernan.