COMP248: Program Documentation
Overview
A very important part of any assignment you submit is the documentation associated with your program. Small programs can be internally self-documenting, but as soon as a program consists of more than one file, it becomes appropriate to consider providing a separate word-processed document.
There are really three aspects to consider in documenting your code to a high standard: the associated program description and test runs; the in-program commenting; and general presentational quality.
Program Description
Your code is being written for someone else to read. That's true when you do an assignment that will be marked, and it's also true when you do a piece of work when you are coding for a job: someone, somewhere, long after you have gone, will have to maintain your program. Even in those cases where your code is relatively throwaway, you yourself may have to come back to it to maintain it, and if you have not documented the program adequately, you'll be creating work for yourself.
Each program should have an associated description that says something about the purpose of the program and its limitations. For small programs you can do this in the program header; for larger programs it's more appropriate to do this in a separate document.
You can view this task as something like telling a story: you need to inform the reader about the overall nature of your program, what it is for, and what it cannot do. You can use the program description to explain the general approach you have taken, to highlight any special tricks or techniques you have used, and to discuss test results. By producing good documentation, you will convince the reader that you have really understood the problem to be solved, and the approach that you have taken to solving it.
Many programmers find documentation hard to do. A common complaint of many employers is the poor quality of programmers' ability to document to an appropriate standard -- take advantage of the University context to get practice in this important skill.
In-Program Commenting
In-program commenting is extremely important. You use it to make clear what is going on in the program. Make each logical section or block of code very distinct using space and lines of various kinds, and document each logical section consistently. Whenever you use a technique that is even slightly complicated, explain what you are doing in the commenting and why. In many programs where specific cases of data are being dealt with, provide examples in the comments that motivate what you are doing. Don't just repeat line for line what the code is doing, since with appropriate use of symbolic names that will often be obvious; instead, use your comments to provide a picture at a slightly higher level that the code itself. At the same time, don't assume anything is obvious: it may have been obvious to you when you wrote it, but it won't be in two weeks' time.
General Presentational Quality
Be proud of your work, and demonstrate your pride by submitting an aesthetically pleasing well-presented result. This doesn't mean you have to spend money on expensive binding: you can achieve quality results very cheaply. So, for example, make sure your hard copy is fronted by a cover sheet that clearly displays all the relevant information, such as the name of the assignment, the unit it is for, your name and student number and the date. Where there are multiple parts to your submission, put some thought into how you can reflect that structure in your documentation. You don't have to do anything ornate: ultimately the goal is a functional one, in that you want your submission to be easily navigable by the reader, but aesthetics play a significant role in this. This is important both for any associated program description as well as the code itself: use lines and other structuring elements to indicate the overall structure of your program, to make it easy to find things in the code.