18-348 Coding Style Guidelines

General coding style guidelines:

1. Each file shall have as a minimum the following components:
   • 1.1 An initial comment with, as a minimum, the following information:
     • 1.1.1. File name and project name/number (e.g., Lab 4; file prog1.asm)
     • 1.1.2. Lab group number and lab group members (names)
     • 1.1.3. CPU type and compiler used
     • 1.1.4. Purpose of module or other summary of contents
     • 1.1.5. Creation date or date of last modification
       
     • 1.1.6. Summary of externally visible items, such as call signature of routine or global variable effects
   • 1.2. Global variable and constant definitions
   • 1.3. Main procedure or most important procedure in module
   • 1.4. Support routines
2. Programs shall make use of the following good practices:
   • Initialize each variable before it is read for the first time
   • All procedures will document the procedure name, purpose, input variables, output variables
   • All variables shall be descriptive (e.g., "Clock_Ticks", not "Temp43")
   • There shall be a comment every four lines.  There should be a comment every one or two lines.
   • Every loop, subroutine, and main control structure shall have a higher level comment indicating its purpose.
3. Programs shall refrain from:
   • Using "magic numbers" rather than defined constant values
   • Using comments that wrap around a standard 8.5"x11" sheet of paper in portrait mode. As a practical matter, this means lines should not exceed 65 characters and shall not exceed 75 characters.

Assembly-Specific Guidelines:

1. Each procedure shall provide as a comment a "picture" or other summary of stack contents during the main execution portion so programmers can track where variables are with respect to the stack pointer or frame pointer.
2. Called subroutines are responsible for saving and restoring all registers in calling program, except those documented as being used for parameter passing
3. Subroutines shall be followed by a whole line comment that indicates the name of the subroutine, for example "; routine MyProcCall ends here"
   
4. The following items shall always begin in the same column (each type begins in the same column, but different types might begin in different columns):
   • Labels (column 1)
   • Whole-line comments
   • Assembly instructions
   • Assembler directives (e.g., EQU and ORG)
   • Operands
   • End-of-comment lines (to the maximum extent practicable)
5. High-level comments may begin at column 1 or at the same column as assembly instructions.

C-Specific Guidelines:

1. Each program shall have an identically base-named ".h" and ".c" file. The .h file shall have header information and the .c file shall contain the code implementation.
2. C++ constructs can be used to the extent supported by course tools (e.g., use of "//" for whole-line comment)