Information Technology Reference
In-Depth Information
13.4.1 Commenting Code
Commenting code is extremely important to understanding it. Another item that
can be automatically generated is documentation. This leads to strict and specific
comment styles. Comments should be verbose enough to convey understanding,
but not lengthy and complex creating more confusion than mere source code.
Schach defines the minimal coding requirements for a code artifact as follows
(Schach
2007
):
1. The name of the artifact.
2. A brief description of what the code artifact does.
3. The programmer's name.
4. The date the artifact was coded.
5. The date the artifact was approved.
6. The name of the person who approved the artifact.
7. The arguments of the artifact.
8. A list of each variable in the artifact and a brief description of each variable.
9. The names of any files accessed by this code artifact.
10. Input-Output, if any.
11. Error handling capabilities.
12. The name of the file containing test data (used for regression testing).
13. A listing of each modification made to the artifact, the date the modification was
made, who performed the modification and who approved the modification.
14. Any known faults.
13.4.1.1 End User Documentation
Documentation for the end user is an important part of the development process.
Though it may not necessarily take shape during the implementation phase of
development, it is important to be mindful of the aspects that it should cover when
completed. For any system to be complete, documentation must be provided at
multiple levels to suit users of different skills and purposes. Sommerville provides
the following breakdown of documentation, as well as a description of each dif-
ferent variety. All items listed should be included with the project deliverables
(Sommerville
2004
) (Fig.
13.11
).
The following is a brief description of the five documents listed above (Som-
merville
2004
):
1. A functional description should provide users with the knowledge of what
services the product provides. This document should be comprehensive enough
for the user to determine if this will solve the task at hand.
2. An introductory manual is an invaluable piece of documentation. This docu-
ment should have a liberal amount of pictures and samples. It has to also be
deemed appropriate to cover common error avoidance and recovery in this
work.
