computer science courses. Addi- tionally, it discusses the establishment of standards address- ing both the procedure- and object-oriented programming.
DOCUMENTATION
STANDARDS
IN THE UNDERGRADUATE
COMPUTER
Ren&e A. McCauley, Ursula Jackson, and Bill Computer Science Department
SCIENCE
CURRICULUM
Manaris
University of Southwestern Louisiana Box 41771 – USL Station Lafayette, LA 70504 {mccauley,
jackson,
ABSTRACT This paper focuses on documentation standards and their employment throughout the undergraduate computer science curriculum. Specifically, it presents the motivation for a set of well-defined programming-intensive tionally,
documentation
computer
ing both the procedureparadigms.
Finally,
●
University curricula often lack courses in severat topics necessary for professional software production.
✎
Many undergraduate
(Jones, 1995)
and object-oriented
Addi-
dents to believe development
programming experiences
●
in
using such standards to teach many software engineering principles along with required concepts in the undergraduate computer science curriculum.
Software
engineering
principles
are typically
relegated
to
and Engineering”
the common (Tucker,
requirements
experiences 1995)
many educators advocate that certain software principles
may be most effectively
taught if in-
throughout the CS curricuet al., 1995; McCauley, et
al., 1995; Oliver & Dalbey, 1994; Roberg6 & Suriano, 1994). Our philosophy is that software engineering principles are an integral part of the entire undergraduate CS curriculum aIld that practical software engineering experiences presented early in the curriculum are influential to the success of students in upper-level courses and beyond. Ad-
other courses. Consequently, in an effort to bring practical software engineering experiences into the core CS curricu-
as one of the nine subject
area should be included
software
ditionally, we believe that a consistent approach to systems development must be presented to students and reinforced in
lum, we have modified
areas that should be required in all undergraduate programs in computing, yet it gives no specific guidelines on how or where in the curriculum
detailed
approach is not necessary. (Weide, 1995)
troduced early and reinforced lum (Gersting, 1994, Hilburn,
et al., 1995). This practice has been supported by published recommendations on the structure and organization of undergraduate computer science (CS) curricula. Specifically, “Curriculum ’78” recommends an advanced-level elective course in “Software Design and Development” (ACM Curriculum Committee, 1979). The ACM/IEEE-CS Joint Task Force in Computing Curricula 1991 identifies “Softwtie Methodology
that a systematic,
is
This leads stu-
of more practicat software engineering into the curriculum. (Wall Street Journal,
engineering
junior- or senior-level software engineering courses or to an optional area of concentration in the curriculum (Hilburn,
lack a con-
The U.S. software industry is calling for the integration
Accordingly,
INTRODUCTION
programs
design and development
taught from one course to the next.
of standards address-
it relates the authors’
computing
sistency in how software
standards for
science courses.
it discusses the establishment
manaris} @usl.edu
the content of many courses in our
program, and have adapted/updated our procedures for developing and evaluating student programming assignments.
of this
et al., 1991).
BACKGROUND In
This practice of postponing introduction of software engineering principles until after students have spent considerable effort in software development has recently come under fire from several directions. For example, the fol lowing concerns have been expressed regarding the way we cover software engineering principles within undergraduate curricula:
the
fall
of
1994,
our
department
adopted
a set
of well-defined documentation standards to be used in programming-intensive CS courses. These standards specify the (a) design method students are expected to use to produce systems, (b) required internal and external program documentation, (c) details on the physical organization of systems, (d) desirable characteristics of developed code, and (e) information related to the evaluation of the student’s effort/deliverables. Moreover, in terms of external program
Permieaion to copy without fee all or part of this material ia gtanted provided that the copies are not made or diatfibrded for direct commemial advantage, tbe ACM copyright notice and the title of the publication and its date appear, and notice is given that copying !s by permission of the Association for Computing Machinery. To copy otherwise or to republish, requires a fee antior specific permission. SIGCSE ’96 2/96 Philadelphia, PA USA Of 996 ACM 0-09791 -757-X/96/0002 ....60.6O
documentation, students are required to present clearly the deliverables of the software engineering activities related to the analysis, design, implementation, and verification of systems. Finally, since our curriculum includes courses
242
that employ both procedure-
and object-oriented
ment methods, we established
both procedure-
develop-
software, .
and object-
oriented design versions of the staudmds. (For an excerpt of the object-oriented
version of the documentation
standards,
●
of these department-wide
standards,
we observed that there was no continuity in the way design, development, and documentation was taught across the cttrriculum. Additionally, we perceived that students in upperdivislon project-oriented courses were ill-prepared to manage the large programming
projects
that those courses re-
Since many long-term
learned m the introductory
programming
engineering
principles
remainder
Our
three-course
introductory
the in
is a tradi-
gineering,)’
The programming
respectively.
material
testing
techniques
for
STANDARDS
to assist them in developing Softwwe
software
engineering
ed-
tematic approach to systems development,
in that their use
encourages students to spend a sigtuficant
amount of time
and documenting
software
systems before they
standards, students are ex-
standards for our program,
of
we consulted the
documentation standards presented in Gersting’s “A Software Engineering ‘Frosting’ on a Traditional CS-1 Course” (Gersting, 1994). Both Gersting’s standards and the stmdards discussed herein specify the content and the format
assignments in
of the written-documentation each software product.
assignments, whereas CS3 includes four
of software engineering
guidelines
In developing
package to be submitted
The written documentation
software engineering activities mentation, and verification. As indicated
into all three of
with
required
of students consists of four parts, which correspond
to six assignments. In addition to the data structures and algorithms content, both courses emphasize the use of software engineering techniques in the design and development of software solutions. Currently, we incorporate a large collection
OF THE
the use of these documentation
both classes are large and complex in relation to the assignments in CS 1. Typically, CS2 includes approximately four programming
employ a variety of software verifying systems.
posed to some of the issues related to the development high-quality software in real-world environments.
course. The CS2 and CS3 courses are focused on data structures, algorithms, and the development of relatively large software systems. The CS2 and CS3 courses are approprito Data Structures and Software Data Structures and Software En-
●
of
start coding them, which consequently results in the development of better designs and products. Also, through
tional depth-first software development-intensive sequence. The first course, CS 1, is an one-semester problem-solving
ate y titled “Introduction Design” and “Advanced
use (or reuse) existing modules in the development new systems, and
designing
CS sequence.
CS sequence
and
ucators and practitioners hold that there is a high correlation between a systematic approach to systems development and the quality of the resultant products (Weide, 1995). The documentation standards presented herein facilitate a sys-
is most bene-
of this section is devoted to our experiences
using the standards in the introductory
modification,
large software systems,
solutions in a systematic manner.
across the curriculum. Because, as discussed above, we believe that the introduction of such standards to support the of software
of relatively
●
defined
the
curriculum changes and documentation standards in those courses first. Since then, we have employed the standards
to students when done early in the curriculum,
and doc-
Our primary objective in developing the documentation standards was to present students with a set of clear, well-
practices are
CS sequence, we introduced
development,
systems,
gain experience in the development,
ESTABLISHMENT
quire. The recognition of these facts prompted us to change the way we teach software development throughout the cur-
ficial
of software
maintenance
Prior to our adoption
teaching
in the specification,
umentation
see the appendix.1)
riculum.
participate
to the
of analysis, design, imple-
above, Gersting’s
work
has been used as a
these classes. Since most data structures texts cover little or
starting point in the development of our standards. However, due to the nature of our program, we made slgmficant
no software engineering
modifications
material,
we make reading materi-
als and notes available from other sources. Furthermore, we concentrate on techniques and processes in software development which motivate the need for the documentation standards discussed herein. Our software-engineeringrelated learning objectives are that students:
.
in the introductory
to these standards and introduced
oriented version.
For the procedure-oriented
standards, we moditied
Gersting’s
an object-
version of the
design guidelines
to fo-
cus on the use of abstract data types and the decomposition of solutions into separately compiled units. For the object-oriented version, we introduced new design guidelines which focus on objects and inter-object communica-
CS sequence
become aware of software engineering models and issues concerned with the development of high-quality
I Completecopiesof the documwtatlon standardsare avadableVUI usl.edti-raml.f3.T/documetltatiotl. html), emad, or wW~ (}lttp:/*.uc.v. [1S mad.
243
tion. Additionally, we modified the requirements documentation of the standards to include lnforrnatl on related to the user-interface of the system and exclttcte mformatiou related to processing. We enhanced the implementation dt)cumentation to specify desirable charactermtics of the developed code including details on the physical orgtnizatlon of the
I.
II.
Requirements
Documentation Description
1.
Problem
2.
Input Information
3.
Output
4.
User Interface
objectives of the assignment and the course. ways we have used the standards include:
.
Information Information
.
Design Documentation
Students are given a problem statement and asked to develop a complete written-documentation package. Students are given the requirements asked to complete the written
Description
Some of the
documentation
documentation
and
package.
1.
System Architecture
2.
Object Information
Students develop the requirements documentation as a group under the direction of the teacher. The teacher
3.
System Driver
then gives them a portion of the design documentation,
4.
Diagrams
●
Information
such as the system architecture
III.
Implementation Documentation 1. Program Code
IV.
Verification and Validation 1. Test data 2. Test results 3. Operating directions
object interaction develop
Documentation
diagram.
the remainder
information
and the
Students are expected to
of the written-documentation
package. ✎
Students are given the requirements or design documentation for a problem with which they are famili,m and are asked to critique
it in some manner appropri-
ate to the portion of the documentation under review. For example, they may be asked to comment on the Figure 1. Outline of the written documentation.
strengths possibly ●
and weaknesses offer alternative
of a proposed
design and
solutions.
Students are given access to a documentation
package
system, internal program documentation, and stylistic conventions. The outline of the object-oriented version of the
consisting of the requirements, design, and implementation documentation for a specific system, in addi-
standards is shown in Figure
tion to a partial implementation of this system. Subsequently, they are asked to develop a set of functional
The written
documentation
1. required
extensive as what might be required engineering
of students is not as
project course or in a real-world
duction environment.
However,
a taste of what is normally
or structural test data sets and use the data to test the given system.
in an actual softwaresoftware pro-
✎
the standards give students
required
in practice,
and help
Students are given a complete documentation package and access to a working system and asked to maintain or modify
them appreciate the difficulties associated with the development of large, robust, and maintainable software systems.
the system by extending
then do appropriate ✎
Students work
in teams to develop
design parts of the documentation USE OF THE
STANDARDS
The documentation
standards
ducive to the development
it in some way and
testing, the analysis and package,
discussed
herein
are con-
✎
Students work in teams to develop a complete writtendocumentation
of software in a systematic way.
Students are required to submit software solutions in increments that are marked, graded, aIld returned to them in a
package.
We take the documentation standards very seriously and grade them with attention to detail. Typically, fifty per-
timely manner so that they can be used and modified in preparing the next part of the solution. If timely grading of
cent of the grade on a programming
project
solution increments is not feasible, the teacher can present a
the written
with
possible solution and discuss it in class, so that students may
is determined
continue working on the assignment even though they have not received comments on their own submission. These solution increments are the requirements, design, implemen-
presentation
documentation
ifications.
that attempts to validate the system under production and identify inherent errors as early in the process as possible.
DISCUSSION
When the final product is submitted,
students are required to
written-documentation
submitted
by the content, completeness, of the documentation.
sequence, namely: program-
ming assignments in a variety of ways, depending
upon the
This grade
accuracy, and
The other fifty percent
Prior to the establishment of these standards in conjunction with the incremental submission of solutions, programming projects followed the traditional assignment-grading
pack-
We have found the standards useful in organizing
is based on
it.
of the grade is based on the program itself, which is graded according to the quality of its appearance and organization, its correctness, and the extent to which it satisfies its spec-
tation, and verification and validation portions of the documentation package. This simulates a quality review process
submit an updated, complete age.
but are
expected to develop and test their code individually
1.
244
teachers gave assignments,
2.
students completed for grading, and
assignments
3.
teachers began grading
submitted
ously, students began working signment before getting
and submitted work;
them
the 8th SEI Conference on Software Engineering Education, pp. 87-97.
simultane-
on the next project as-
Jones, C. (1995). puter,
any feedback on the one just
“Gaps in Programming
28(4), pp.
Education,”
Com-
70-71.
completed. Managing the incremental submission and simulated review process places a significant burden on the instructor in terms of time. However, the benefits to the students make the effort worthwhile. These benefits include: 1.
early and steady feedback on developing
2.
a detailed
3.
approach to software
systems,
Oliver,
in a sequence of courses, and
exposure
software
development
S.R. & Dalbey,
Bulletin,
26(l),
pp.
use of an organization-wide mentation,
b. c.
participation in a quality review process, generation of test cases and documentation results,
364-65.
J. (1994).
“A Software
Develop-
for CS 1 and CS2,”
SIGCSE
169–173.
experiRoberg6, J. & Suriano,
a.
working
27(1), pp.
ment Process Laboratory
ences, such as:
d.
SIGCSE Bulletin,
design and develop-
ment that is reinforced to practical
McCauley, R.A, Archer, C., Date, N., Mili, R., Roberg6, J. & Taylor, H. (1995), “The Effective Integration of Software Engineering Principles Throughout the Undergraduate Computer Science Curriculum,” Panel Abstract,
Teach Software
standard for docu-
C. (1994).
Engineering
tory Computer Science Curriculum,” 26(l), pp. 106110.
of test
Tucker, A. B., Ed. (1991).
Computing
port of the A CM/IEEE-CS
with code or designs developed
“Using
Principles
by oth-
ACM
Laboratories
to
in the IntroducSIGCSE Bulletin,
Curricula
Joint Curriculum
1991: ReTask Force,
Press.
ers, e.
working
f.
maintenance
in teams, of existing
g
management
of relatively
Wall Street Journal
(1995).
Say Software B1.
Companies,”
systems, and large systems.
Weide, B.W. (1995). SUMMARY This
paper
described
the
establishment
and use of
“ ‘More Practice, Less Theory,’ February
“Challenges
the Undergraduate Computing 28(8), Pp. 31–32.
a
21, 1995, Section
of Software Curriculum,”
Design and Computer,
department-wide standard for the development and documentation of programming assignments by students. We have found that through
the use of such standards, we can
APPENDIX
teach very naturally and effective y many software engineering principles along with the required concepts in the
This
curriculum.
sign portion
The standmds have proved to be useful across
section
includes
an abbreviated
of the object-oriented
version
of the de-
version of the standards.
the curriculum in organizing programming assignments in a variety of ways. This allows students to experience prac-
(Complete copies of both the procedure- and object-oriented versions of the standards are available through WWW
tical software
(http:lwww,
riculum,
development
activities
throughout
rather than in only a single junior-
software engineering
the cur-
or senior-level
email,
course.
REFERENCES
Programming Documentation Standard Object-Oriented Version
ACM Curriculum Committee (1979). “Curriculum ’78: Recommendations for the Undergraduate Program in Computer Science,” 22(3), pp.147-166. Gersting, J.L. (1994).
Communications
of the ACM,
“A Software Engineering
II.
T, B., Hirrnanpour,
“The Integration Computer
I. & Koruecky,
of Software Engineering
Science Curriculum,”
Documentation
object-oriented
design method.
The solution to the problem will be a software system that is comprised of a system driver and a set of interacting
A. (1995). into a
in Proceedings
Design
The purpose of this section of the documentation is to describe a plan for the solution of the problem using an
‘Frosting’
on a Traditional CS - 1 Course,” SIGCSE Bulletin, 26(l), Pp. 233-37. Hilburn,
ucs.usl.edu/-raml.3.75/documentation.html),
or US mail. )
objects, The system driver is the algorithm the usage of the objects in the system.
of
245
that coordinates
The basic steps in the process of object-oriented adapted from Booch2, are: ●
●
●
●
. .
Identify Identify
objects. the attributes
Identify
operations
design,
of each object.
that affect each objeet and the op-
erations that each object must initiate. Establish the visibility of each object
in relation
to 11.3 System
Information design,
system,
gating
Object
This section describes, in a readable and modular form, how the system driver
Information
Each object belongs to a class. Each class is specified
in
terms of its attributes (data members) and its operations (methods or member functions). For each class specification, include the following
the software.
must include
logic
This description
of
of the must be
11.4 Diagrams
text and information: be summarized
11.2.1 Class Information Name: Name the class.
11.4.1 Object Interaction
Description:
describe its purpose.
Show a diagram that illustrates
the base class, if appropriate.
system. This diagram
Base Class: Identify
The description
the detailed
driver, including flow of control. presented in pseudocode.
The design effort will
Briefly
is the co-
tasks to objects.
the system driver controls iI.2
the system driver
ordinating atgorithm of the software product. The driver may consist of several subroutines. Often the driver is only responsible for processing user commands and then dele-
Description
describe its role in the overall
Driver
In an object-oriented
This section includes the system driver and a list of the objects that comprise the system. For each component briefly
11.2.4 Objects List all objects of the given class.
other objects. Establish the interface of each object. Implement each object.
11.1 System Architecture
iwgument (parameter) preceded by a comment stating the parameter-passing mechanism used (in, out, or in/out).
by three diagrams:
Diagram the calling interaction
of the
consists of an ellipse for the system
driver, a box for each class, and directed lines from clients 11.2.2 Attributes
(data
members)
(Repeat for
each at-
to servers. Each box contains its operations.
the name of the class and
tribute. ) Name: Name the attribute. Description: Briefly describe its function or purpose. ~ Indicate its data type or class. Range of acceptable values: Identify the acceptable range
Show an inheritance diagram for each inheritance scheme. The inheritance diagrams must follow the notation proposed
of values,
by Rumbaugh,
11.4,2 Inheritance
et al.3.
11.4.3 Aggregation 11.2.3 Operations
Precondition(s): Give input assertion(s) describing the truths that the operation expects at the moment of its invocation. Postcondition(s): Give output assertion(s) describing the state of the computation at the moment the function terminates. Give the function
2 G. Booth. janun/Cumnungs
prototype
with
Diagram
Show an aggregation diagram for atl classes that have aggregates. One diagram will be needed for each aggregation relationship. Each relationship will include the object that
(Repeat for each operation.)
Name: Name the operation. Description: Briefly describe the task it performs.
Prototype:
Diagram
contains or exclusively manages the object of another class, and the object of that other class. Each class will be represented exclusively by its name, and the relationship will be indicated by a directed line, from container to contained. On the dire~ted line, the cardmality (1:1, 1:n, etc., of the relationship
will
be indicated.
each formal
Object-Oriented Design with Applications, Publishing Company, 1991.
The Ben-
246
3
Rumbaugh, J., M. Bkdrz W. Premerlani, F. Eddy, and W. Object-Oriented Modelwrg and Destgn, Prentice-Hall, 1991.
.orensen.
