Brief Documentation Guide
Comments must be used to document the problem the code solves.
You should include at the very top of your code a comment that explains in detail the
problem the code solves and how it solves it.
Approximately 2 to 7 lines for labs
Approximately 7 to 30 lines for assignments
Comments should explain any mathematics or formula used in the code.
You should document the units of an indenter if it has related units, eg. metres.
Comments should explain why an approach is taken, if there are multiple possible
approaches.
Comments should explain what blocks or steps in your code do, if significant.
A person that understands the fundamentals of C code should be able to read your code and
comments and know what it does without having to run it.
You should not comment every line.
You should explain when using iteration, what is being iterated.
You do not have to explain C code to the reader unless asked.
The number and size of comments is not a measure of how well you have documented your
code.
Function descriptions must be used
Implicit documentation and style:
Variables must be limited to an appropriate scope.
Variables must be named appropriately such that they can be easily identified
Early exiting from loops or functions are avoided unless necessary
White space is used to separate various parts of the code for clarity
Indentation style used is the Allman style
Brief Documentation Guide