CSE 283 Introduction to Object Oriented Design

Barbara Nostrand, Ph.D.


Writing File Headers and Revision History Blocks

You should begin each Java source code file with File Headers.  The following items should be included as a minimum: 

Each entry in the Revision History should contain the following information.  The Revision Identifier should appear as a comment at the location(s) of each revision. 

Writing Technical Reports

Technical Reports are a common feature of project development in both industry and academe.  The purpose of a technical report is to allow others to understand,  utilize,  and continue your work.  What follows is a brief outline of the contents of a technical report.  In practice,  a technical report may require extra sections such as:  a description of prior work,  a description of future work,  a bibliography,  and various appendices such as a hardware reference guide,  circuit diagrams,  code listings,  or mechanical drawings. 

SectionDescriptionContents
1Title PageHere you typically find such things as: Title,  Author(s),  Institutional Affiliation,  and Funding Statements
2Table of ContentsThis part is pretty much what you would expect.  However,  larger technical reports may have added tables of contents for such things as figures and tables.  If the technical report is sufficiently short,  the table of contents may be merged with the title page or eliminated all together. 
3IntroductionHere you state the objectives of the project and give a summary of the entire technical report.  Although not typically part of a technical report,  you should itemize the contributions of each contributor to the project in this section. 
4Theory of OperationHere you discuss how and why your system works or is supposed to work.  Here you will find such things as system block diagrams,  algorithm descriptions,  and similar material. 
5User's ManualInstructs the user on how to set up,  initiate,  control,  and otherwise use the system. 
6System ArchitectureThis section describes the major components of the system,  specifies communication between the components,  identifies any external dependencies,  and describes performance factors. 
7Detailed DesignFor software,  the detailed design needs to specify at a minimum: 
  1. The preconditions for each method. 
  2. The postconditions for each method. 
  3. The side-effects of each method. 
  4. Any critical timing considerations. 
The Java development system provides a mechanism for producing standardized detailed manual page entries for each class and its objects.  The Java documentation standard mandates grouping methods descriptions with their classes. 
8Test Procedure Describes how the system is to be tested.  The tests to be performed must thoroughly exercise the system and allow the person performing the test to isolate the problem. 
9Test Report In its simplest form,  a test report is simply a table indicating the test performed,  the expected result,  and the result actually obtained. 


Last modified: 2007 SEP 11
bnostran@syr.edu