6 Documentation

DOCUMENTATION

 

Documentation provides a foundation for successful engineering and, more important, guidance for software support. Moreover, documentation is a Descriptive information (e.g., hardcopy manuals, on-line help files, Web sites) that portrays the use and/or operation of the system.

 

Documentation is important for software engineering to improve the software quality. It is often neglected by many software programmers. Most of the companies and projects have failed due to poor quality documentation. Documentation is the instruction manual about the software products and services. It provides the information to the technical user how to handle and analyze the products without getting help from others. In software quality management, a document acts as a communication medium between members of the development team. Documentation includes source code, instructional items, error code where ever required. It may exist in any formats like PDF, Word or CDs. A qualified document provides information for management to help them to plan, budget and schedule the software development process. If you find your programmer does not, or will not, document their software, and then it is best to get rid of them now. If the software is undocumented and they leave, the only option is to start again and rewrite it all. Picking up the pieces of poorly documented software is a very expensive and a time consuming exercise it’s cheaper to start from scratch.

REASONS TO DOCUMENT

The documentation can be more useful to understand the software, so that the software can be understood by other people and advanced projects can be undertaken. Moreover, users can use parts of the code for other projects and it is helpful for making the life easier.

 

SOFTWARE PROGRAMMERS

 

Many software programmers are reluctant to document their software they may wish to have exclusive control over the project and its further development. Some may even use it as a means to apply pressure on their companies for a pay rise or a better position. They may also wish to hide their ignorance of software programming or the understanding of the project in which they are engaged. Some think documentation is a boring task and slows down their creativity. In reality software documentation is essential for any project, particularly if it is a team effort.

 

GUIDELINES FOR DOCUMENTATION

 

Each company will have its own standards for titles and document numbers. It may also have a change control document procedure in place. This information is best included at the beginning of any software. Release or version numbers are a good idea for software that’s ready for commercial exploitation. Use Version 1.0 for the first software package, Version 1.1 for the first re-issue of the software, with minor modifications. The first digit is only changed for major enhancements of the software (eg, Version 2.0). Keep the documentation easy to read, clear, concise and avoid jargon. The first part of the program should contain a brief description of the overall function of the program. Do not launch into technical details straight away. Slowly build up the description, unveiling details where they are needed, such as in each method and on each line of code.

 

DISTRIBUTED CODE

 

Often a program code is distributed throughout different files. Eg. Picture Files, Data Files, Sound Files, Packages, Library Files, Include Files

 

ARCHIVE FILES

 

Ensure documentation includes what files are needed and where they are located. You may have to copy and compile / run programs on other machines Naming Conventions

 

•         Class names should begin with an uppercase letter and have mixed case. For example, TimeZone and InputReader.

  • Function names (method names) should begin with a lowercase letter and have mixed case when appropriate. For example, readInteger of getDefault.
  • Variable names should not include uppercase letters. They may include underscores to separate words. For example acceleration, current_time.
  • Constants should be in all capital letters. They may also use underscores and digits. For example, VELOCITY_OF_LIGHT.

 

METHOD DESCRIPTIONS

  • Give the method a title, give an overall description of what the method does, what are the input parameters, and what data types they are, what is returned from the method, and what data type it is, give a description for each of the local constants and variables, for each line of code give a brief description of what that line does

INDENTATION AND SPACING

 

A consistent indentation style makes programs clear and easy to read. Indentation is used to illustrate structural relationships among the program’s components or statements. The programmer should indent each subcomponent or statement two spaces more than the structure within which it is nested.

RandomAccessFile Wdata = new RandomAccessFile(FileInfo,”rw”); for(C=0;C<=Dcnt-10;C=C+NoCH)

{

 for(int N=0;N<=NoCH-1;N++)

 {

     int DAN = Darray[C+N];

     String SDAN = Integer.toString(DAN);

     Wdata.writeBytes(SDAN + ” “);

 }

      Wdata.writeBytes(“\n”);

}

JAVA AUTOMATIC DOCUMENTATION

 

In the Java Developmet Kit there is a utility to automatically produce documentation. This documentation includes the users comment statements placed between //* and */ . It will also generate documentation of the class and hierarchy structure of your program. Use javadoc comments at the beginning of the program to state your name, class, and give a brief description for the program. Use javadoc comments to describe an entire method. Use line comments to describe steps inside a method. Indent your statement two spaces. Leave a blank line before a comment line or a comment paragraph.

 

DESIGN DOCUMENTATION

 

The Design documentation deals with the specification which addresses different aspects of the design model and is completed as the designer refines his representation of the software. First, the overall scope of the design effort is described in the document. Much of the information presented here is derived from the System Specification and the analysis model (Software Requirements Specification).

 

Next, the data design is specified in the document. Database structure, any external file structures, internal data structures, and a cross reference that connects data objects to specific files are all defined in the document. The architectural design indicates how the program architecture has been derived from the analysis model. In addition, structure charts are used to represent the module hierarchy (if applicable). The design of external and internal program interfaces is represented and a detailed design of the human/machine interface is described in the document. In some cases, a detailed prototype of a Graphical User Interface (GUI) may be represented. Components—separately addressable elements of software such as subroutines, functions, or procedures—are initially described with an English-language processing narrative. The processing narrative explains the procedural function of a component (module). Later, a procedural design tool is used to translate the narrative into a structured description. The Design Specification contains a requirements cross reference. The purpose of this cross reference (usually represented as a simple matrix) is (1) to establish that all requirements are satisfied by the software design and (2) to indicate which components are critical to the implementation of specific requirements.

The first stage in the development of test documentation is also contained in the design document. Once program structure and interfaces have been established, it is possible to develop guidelines for testing of individual modules and integration of the entire package. In some cases, a detailed specification of test procedures occurs in parallel with design. In such cases, this section may be deleted from the Design Specification. Design constraints, such as physical memory limitations or the necessity for a specialized external interface, may dictate special requirements for assembling or packaging of software are also specified in the document. Special considerations caused by the necessity for program overlay, virtual memory management, high-speed processing, or other factors may cause modification in design derived from information flow or structure. In addition, it describes the approach that will be used to transfer software to a customer site. Finally, the Design Specification contains supplementary data. Algorithm descriptions, alternative procedures, tabular data, excerpts from other documents, and other relevant information are presented as a special note or as a separate appendix. It may be advisable to develop a Preliminary Operations/Installation Manual and include it as an appendix to the design document.

TESTING DOCUMENTATION

 

The term software testing conjures images of large numbers of test cases prepared to exercise computer programs and the data that they manipulate. The definition of software development process is important to note that testing must also extend to the third element of the software configuration—documentation. Errors in documentation can be as devastating to the acceptance of the program as errors in data or source code. Nothing is more frustrating than following a user guide or an on-line help facility exactly and getting results or behaviors that do not coincide with those predicted by the documentation. It is for this reason that that documentation testing should be a meaningful part of every software test plan.

 

Comprehensive test case design methods for real-time systems have yet to evolve. However, an overall four-step strategy can be proposed: Task testing. The first step in the testing of real-time software is to test each task independently. That is, white-box and black-box tests are designed and executed for each task. Each task is executed independently during these tests. Task testing uncovers errors in logic and function but not timing or behavior. Behavioral testing. Using system models created with Computer Aided Software Engineering (CASE) tools, it is possible to simulate the behavior of a real-time system and examine its behavior as a consequence of external events. These analysis activities can serve as the basis for the design of test cases that are conducted when the real-time software has been built. Using a technique that is similar to equivalence partitioning, events (e.g., interrupts, control signals) are categorized for testing. For example, events for the photocopier might be user interrupts (e.g., reset counter), mechanical interrupts (e.g., paper jammed), system interrupts (e.g., toner low), and failure modes (e.g., roller overheated). Each of these events is tested individually and the behavior of the executable system is examined to detect errors that occur as a consequence of processing associated with these events. The behavior of the system model (developed during the analysis activity) and the executable software can be compared for conformance. Once each class of events has been tested, events are presented to the system in random order and with random frequency. The behavior of the software is examined to detect behavior errors and they are recorded in the document.

 

DOCUMENTING INTER TASK TESTING

 

Once errors in individual tasks and in system behavior have been isolated, testing shifts to time-related errors. Asynchronous tasks that are known to communicate with one another are tested with different data rates and processing load to determine if inter task synchronization errors will occur. In addition, tasks that communicate via a message queue or data store are tested to uncover errors in the sizing of these data storage areas which are documented using the test documentation procedure.

 

DOCUMENTING SYSTEM TESTING

 

System testing is documented by storing how software and hardware are integrated and a full range of system tests are conducted in an attempt to uncover errors at the software/hardware interface. Most real-time systems process interrupts. Therefore, testing the handling of these Boolean events is essential. Using the state transition diagram and the control specification, the tester develops a list of all possible interrupts and the processing that occurs as a consequence of the interrupts.

 

Tests are then designed to assess the following system characteristics:

 

•  Are interrupt priorities properly assigned and properly handled?

 

•  Is processing for each interrupt handled correctly?

  • Does the performance (e.g., processing time) of each interrupt-handling procedure conform to requirements?
  • Does a high volume of interrupts arriving at critical times create problems in function or performance?

In addition, global data areas that are used to transfer information as part of interrupt processing should be tested to assess the potential for the generation of side effects. The document must contain the answers for all these questions.

 

CONCLUSIONS

 

80% of the lifetime cost of a piece of software goes to maintenance. Hardly any software is maintained for its whole life by the original author. Code conventions and documentation improve the readability of the software, allowing software engineers to understand new code more quickly and thoroughly.