Hardware Reference
In-Depth Information
All programs should include, at or near the beginning of the program (the
main()
function in
C), a comment block. The comment block should include at least the following information:
•
The programmer's name
•
The date of creation
•
The operating system and IDE for which the program was written
•
Hardware environment (circuit connection) to run the program
•
Program structure (organization)
•
Algorithm and data structures of the program
•
How to run the program
Below is an example of a program comment header block.
// ********************************************************************************
// Program: RtiMultiplex7segs
// Author: Han-Way Huang
// Build Environment: CodeWarrior IDE under Windows XP
// Date: 07/09/2008
// Hardware connection: shown in Figure 4.18 of Huang's HCS12 text
// Operation: This program shifts seven-segment patterns of 4 consecutive BCD digits
// by using time-multiplexing technique with each pattern lasting for 0.5 s. The
// time-multiplexing operation is controlled by the real-time interrupt. The patterns are
// 1 2 3 4
// 2 3 4 5
// 3 4 5 6
// 4 5 6 7
// 5 6 7 8
// 6 7 8 9
// 7 8 9 0
// 8 9 0 1
// 9 0 1 2
// 0 9 1 2
// ********************************************************************************
Each C function should have a clearly defined task. Writing the comment describing that
task before writing the function can help to keep you straight. Functions should be short enough
so that their meanings can be grasped as a unit by the reader. Normally, one page of code repre-
sents the limit of intellectual complexity that a reader can grasp.
Similar to the main() function, every function should be preceded by a comment describing the
purpose and use of that subroutine. Below is an example of a subroutine comment header block.
// ********************************************************************************
// Function: FindSquareRoot
// Purpose: Computes and returns the square root of a 32-bit unsigned integer
// Parameter: A 32-bit unsigned integer of which the square root is to be found
// Called by: PrimeTest()
// Returned value: the square root of a 32-bit unsigned integer
// Side effects: none
// ********************************************************************************
Search WWH ::
Custom Search