IB Higher Level Dossier Requirements 2006

Prior Syllabus: IB Higher Level Dossier Requirements 2000-2005
Click Here To See What Other IB Teachers Say About Churchill Dossiers.


Donaldson's Dossier Grading Rubic 2006 [Under Construction]: pdf WordPerfect WORD

IBO Computer Science Study Guide 2006 [pdf]

IBO Teacher Support Material 2006 [pdf]

Pages 66-152 of IBO Teacher Support Material 2006 includes discussions and examples of student work to show how the assessment criteria has been applied in the past.

Vade Mecum 2006: Computer Science (pdf) - What Teacher Submits To IBO

Advice From Other IB Schools

Under Construction

Internal Assessment Clarifications by IBO in 2000

This document together with considered interpretations by Mr. Donaldson should be carefully scrutinized as the document and interpretations clarify statements and expectations of Internal Assessment found in the IBO Computer Science syllabus.

Binder With Tabbed Dividers Separating Sections

Code is single spaced. Everything else is double spaced.


Use APA Style Citations and References

IBO Internal Assessment Cover Sheet (front & back)

Program Dossier Cover Page

Table of Contents

Separate Footer For Each Section

Preface
      P1: Preamble
      P2: Acknowledgements
      P3: Annotated Bibliography

Stage A: Analysis
      Criterion A1: Analysis of the Problem [4]
      Criterion A2: Criteria For Success [4]
            JUnit Testing Source Code [0]
      Criterion A3: Prototype Solution [4]

Stage B: Detailed Design
      Criterion B1: Data Structures [4]
      Criterion B2: Algorithms [4]
      Criterion B3: Modular Organization [4]

Stage C: The Program
      Criterion C1: Using Good Programming Style [3]
      Criterion C2: Usability [3]
      Criterion C3: Handling Errors [3]
      Criterion C4: Success of the Program [3]

Stage D: Documentation
      Developer's Documentation: HTML Javadoc Documentation[0]
      Criterion D1: Annotated Hard Copy of the Test Output [4]
      Criterion D2: Evaluating Solutions [4]
            Algorithmic Success: JUnit Results Evaluated[0]
      Criterion D3: User Documentation [3]

Stage E: Holistic Approach
      Criterion E1: Holistic Approach to the Dossier [3]

Mastery Techniques Identified

Index

Demo Movie Using SnagIt

Files On CD

Post Dossier To A Web Page

Binder To House The Dossier

  • Use stiff (cardboard or plastic) dividers with tabs to separate and label each section.

  • Your dossier must contain the following sections:

    • Cover Page: Compare this example.

    • Footer containing automatic page numbering ("Page G1 of 27").

    • Table of Contents: Compare this example: (htm wpd pdf doc)

    • Preface must contain the following subsections.

      • Preamble: An introduction discussing your personal experience with the dossier project.
      • Acknowledgements: Thanking those who were a source of motivation and information.
      • Annotated Bibliography of Material That Influenced This dossier: Use APA Style.

    • Mastery Techniques Identified

    • Title Page for each stage. Include at least one graphic on each title page that is somehow suggestive of the contents of the section identified by that title page.

APA Citations & References

Use APA style citation and reference conventions for software reviews, citing sources of source code that you have integrated into the source code for your dossier program, and all other sources referenced by your dossier program and dossier documentation.

The Program Dossier is a professionl level document. It will be read by professionals when you present it to academic referees and potential employers as an example of your best work in high school. It is not an end-of-chapter exercise!

There are several professional citation styles that are used by various academic and professional communities in the world. Churchill IB Computer Science students are expected to use the citation and referencing style of the APA (American Psychological Association). This is the source of the style found in the Churchill Student Handbook. This is the style preferred by teacher Gerry Donaldson.

When citing electronic references, refer to http://www.apastyle.org/elecref.html.

When citing non-electronic sources, refer to APA Style.

Table of Contents

Preface
      Preamble
      Acknowledgements
      Annotated Bibliography

Stage A: Analysis
      A1: Analysis of the Problem
      A2: Criteria For Success
      A3: Prototype Solution

Stage B: Detailed Design
      B1: Data Structures
      B2: Algorithms
      B3: Modular Organization

Stage C: The Program
      C1: Using Good Programming Style
      C2: Usability
      C3: Handling Errors
      C4: Success of the Program

Stage D: Documentation
      D1: Annotated Hard Copy of the Test Output
      D2: Evaluating Solutions
      D3: User Documentation

Stage E: Holistic Approach

Appendix I: Mastery Techniques Identified

Appendix II: Pre-implementation Planning Documents

Appendix III: Rules of the Game / Chart of Codes

Index

Inclusion on CD: SnagIt Movie Showing Application In Use

Inclusion on CD: All Dossier Related Files

Inclusion on CD: Dossier Web Page

Attachment: CD Containing ALL Dossier Related Files

Separate Footer For Each Section

Create a footer and use the automatic page number function of your wordprocessor to automatically number your pages in your footer. Start renumbering from the beginning of each section of the dossier.

WordPerfect 12
  • Create Footer: Create a footer after: Insert --> Header/Footer... --> Footer A --> Create.

  • Create A Horizontal Line To Section Off Footer From Body of Text: Insert --> Line --> Horizontal Line --> Press "Enter".

  • Determine Alignment: The default positon of the cursor is left alignment, where the cursor is on the extreme left space. To center the cursor, simultaneously press the keys: [Shift][F7]. To right align (move to extreme right) the cursor, simultaneously press the keys: [Alt][F7].

  • Automate Page Numbering: Create automatic page numbering after centering the cursor in the footer: Format --> Page --> Insert Page Number... --> Click "Page" --> Return cursor focus to footer --> type " of " --> Return cursor focus to the dialog box (Insert Page Number) by clicking on "Total Pages".

  • Number Pages By Section: Section A should be numbered A1 of 15, A2 of 15 ... A15 of 15. This way you need not renumber (or reprint) the entire dossier when you add or delete material from a single section.

WORD 2000
  • Create Footer: Create a footer after: View --> Header and Footer --> Switch focus area into a footer by clicking on icon (use mouseover to fine it = "Switch Between Header and Footer").

  • Create A Horizontal Line To Section Off Footer From Body of Text: Format --> Borders and Shading --> Horizontal Line --> Choose style of line by clicking --> Click icon for "Insert clip" (use mouseover to identify this) --> Press "Enter" to move cursor to next line.

  • Determine Alignment: The default positon of the cursor is left alignment, where the cursor is on the extreme left space. To center the cursor from end of left aligned text, press the [Tab] key. To right align (move to extreme right) the cursor from the end of the centered text, press the [Tab] key.

  • Automate Page Numbering: Create automatic page numbering after centering the cursor in the footer: Type the word "Page" followed by a space --> In the floating tool bar, click on the "#" icon (use mouseover to find it) "Insert Page Number" --> type space + "of" + space --> In the floating tool bar, click on the " +++ " icon (use mouseover to find it = "Insert Number of Pages").

  • Number Pages By Section: Section A should be numbered A1 of 15, A2 of 15 ... A15 of 15. This way you need not renumber (or reprint) the entire dossier when you add or delete material from a single section.


Preface


Stage A: Analysis



Criterion A1: Analysing the Problem

The student provides evidence that a systematic method has been used in the analysis of the problem.

This is a definition and clarification of the of the problem. It is a mistake to discuss the solution here.

This is where you place your interview report, questionaire results, use cases (user stories) and use case diagram.

The documentation should contain a thorough discussion and analysis of the problem which is being solved. This should concentrate on the problem and the goals which are being set, not on the method of solution. A good analysis includes sample data, information and requests from the intended user, and possibly some background of how the problem has been solved in the past. - Syllabus 2000, page 47.

This should include a brief statement of the problem as seen by the end-user. A discussion of the problem from the end-user's point of view should take place with both the user's input and desired output being considered.

The analysis should state a clear understanding of the problem and demonstrate how the problem can be solved using a computer-based solution. This analysis should also take into account what input and output will occur and what calculations and/or processes will be necessary to obtain the desired output. -- Syllabus 2000, page 55.

Include the analyses that you did prior to developing your source code. This section should include:

  • A clear indication of how you learned the needs of the potential user(s). Give examples of the sample data that you gathered before you did your program. Examples of sources of sample data are:
    • Requests from the intended user.
    • A survey or questionnaire administered to one or more potential users.
    • Photocopies illustrating fields of a database that already existed that your program will manage. Examples are airline schedules, genealogical databases, horticultural taxonomies.
    • Citations of professional prescriptions that your program must adhere to. Examples are accounting conventions, sports formats, national and international rules and regulations.
    • Published (textual or electronic) descriptions of data that you, the program's designer, analyze with the intent to design a database and management program. Examples are movies in the Entertainment Section of a local newspaper, comparisons of a range of products sold in local supermarkets, a collection of books discovered in a relative's home, variations in the local weather, various automobiles sold in your city.
  • Background on how the problem has been solved in the past.
    "If I have seen further (than Descartes) it is by standing upon the shoulders of Giants." -- Isaac Newton

    Examples of such background are:

    • Analyses of noncomputerized products, past and present.
    • Analyses of existing computer products. These may be commercial software, shareware, freeware or prior student IB dossiers.

Reviews of Software Applications

Administration of Questionnaire

  • Compose and administer a questionnaire for potential users of your software application in order to identify speicific needs of those users that your program may address.



Criterion A2: Criteria For Success

The student relates all of the objectives of the solution to the analysis of the problem, and outlines the limits under which the solution will operate.

You must present criteria here which will be used by you in dealing with later sections of the dossier

  • D3: Including User Documentation

    Evaluating Solution was an important Syllabus criterion for 2000-2005. Here was Com Sci Gate's treatment for that period.

    Evaluating Solutions

    Refer back to the analysis of the problem. State here that you accomplished what you set out to do. Address each of the following areas in separate subsections.

    • Effectiveness
    • Efficiency
    • Improvements and Extensions for Future Development
    • Alternative Approaches

    The conclusion should be a critical analysis of the resulting solution. Efficiency may be discussed in general terms, e.g. BigO notation is not required. Effectiveness should be discussed in relation to the original description of the problem. Suggested improvements and possible extensions should be realistic, e.g. suggestions should not include statements such as "the program would be a lot better if it incorporated some artificial intelligence techniques such as speech recognition and natural language parsing." -- Syllabus 2000, page 53.

    Conclusions/Evaluation

    This item should include reflections on the effectiveness of the programmed solution of the original problem. It should discuss answers to the following questions:

    • did it work?
    • did it work for some data sets, but not others?
    • does the program in its current form have any limitations?

    A thorough evaluation also discusses possible future enhancements that could be made to the program. -- Syllabus 2000, page 58.

    Designing A Testing Strategy was an important Syllabus criterion for 2000-2005. Here was Com Sci Gate's treatment for that period.

    Designing A Testing Strategy

    Testing should follow a plan. It should never be random but should be thorough, well organized, and well documented. A comprehensive testing strategy is desired; that is better than an immense number of random test cases. Testing plans should be described and indicate what candidates consider to be typical data and what results are expected. Candidates should also indicate what situations could arise if invalid data is used. This criterion is separate from the hard copy results of the tests. -- Syllabus 2000, page 50.

    A strategy for testing the program must be included which specifies how the program is expected to behave when differing sets of valid and invalid data are inputted. Thus, the strategy should include consideration of what happens when various branches of the program are activated and must consider/discuss the consequences of inputting invalid data. To do this, a table of inputs and expected outputs should be submitted for a wide range of valid and invalid data. -- Syllabus 2000, page 56.

    You must outline a "wide range of valid data" as well as "some invalid data".

    JUnit Testing should be implemented throughout the dossier program.




    Criterion A3: Prototype Solution

    The student includes an initial design and a complete prototype that corresponds to it and documents user feedback in evalutaing the prototype.

    JUnit Testing must be implemented here. If you haven't already done so, return to criterion A2 and plan your JUnit tests!

    The "prototype solution" must be continuously revisited throughout Stage B - Detailed design.

    Syllabus 2006 states that the prototype solution "must be preceded by an initial design for some of the main objectives that were determined to be the criteria for success. A prototype of the solution should be created."

    Syllabus 2006 defines a prototype thus. "The construction of a simple version of the solution that is used as part of the design process to demonstrate how the system will work."

    Syllabus 2006 then states: "The prototype need not be functional...." Churchill students are to disregard this direction. A non-functional prototype is an oxymoron. By definition and, more importantly, as a crucial developmental tool, a prototype must be functional. The rationale for creating a prototype is to create a significantly functional version of the eventual artifact that may be tested and modified in light of empirical experimentation against that prototype. Churchill students must present a prototype that is functional!

    Wěbopēdia yields three definitions for prototype.

    1. An original type, form, or instance serving as a basis or standard for later stages.
    2. An original, full-scale, and usually working model of a new product or new version of an existing product.
    3. An early, typical example.

    Here is how the term is used in the aerospace industry, according to Encyclopædia Britannica Online. "In the prototype construction phase, emphasis shifts to testing. A customary procedure is to build several test airplanes solely to verify the design. The structural integrity of the aircraft is determined in static and dynamic tests."

    Specifically, a prototype created by Churchill students for their IB dossier must meet the following conditions.

    1. The prototype must implement the ADTs (Abstract Data Types) anticipated by the application design. Specifically:

      If the application implements a linked list, binary search tree, stack, queue, or direct access file handling to store, retrieve and/or modify a data base, then the prototype should implement corresponding JUnit Testing classes and apply methods that store, retrieve and modify one or more (need not be all) of the key fields.

    2. The prototype's corresponding JUnit Testing classes must manipulate data representative of data that will be gathered and generated using the eventual interface, but the prototype may hardwire this experimental data for purposes of testing the prototype's structures and methods.

      • Values that will be read from the keyboard or GUI interface in the final release may be hardwired by the prototype's corresponding JUnit Testing classes, by being loaded into an array from within the source code at compile time.

      • Values that will be read from the keyboard or GUI interface in the final release may be hardwired by the prototype's corresponding JUnit Testing classes, stored in an external text file on the hard disk and read intermittently at run time.

      • Values that will be written to the screen in the final release may be hardwired by the prototype's corresponding JUnit Testing classes, stored in an array and used to generate tables or graphs on the screen at run time.

      • Values that will be written to the screen in the final release may be hardwired by the prototype's corresponding JUnit Testing classes, stored in text files at run time for analysis by hand or with other software after the protype exits execution.

    3. Testing code and experimental data must be physically separated from the prototype's application code. This is accomplished by using corresponding JUnit Testing classes.

      Students must use JUnit testing in implementing source code that tests the prototype's source code.

      Testing code must consist of corresponding JUnit Testing classes that extend application classes. Testing classes must construct objects using a setUp( ) method, test all application methods with JUnit assert( ) methods within corresponding testing methods, and release objects using a tearDown( ) method before exiting the execution of the testing code.

    4. Place the date and a version number in the source code and corresponding JUnit Testing classes of the version(s) of the Prototype Solution. The final version of your dossier should contain progressive versions of prototype source code and corresponding JUnit Testing classes stored in this section of the dossier.

    5. There must be reports detailing feedback from the exection of the prototype. That feedback must be from one or both of two sources.

      • JUnit testing results.

      • User reports.


  • Stage B: Detailed Design

    Learn UML: New For Syllabus 2006

    Documenting the Design Process was the most heavily weighted Syllabus criterion for 2000-2005. Here was Com Sci Gate's treatment for that period.

    Documenting the Design Process for Syllabus 2000-2005

    The solution to the problem should be thoroughly designed before any programs are written, and this design process must be documented. Good top-down design results in a flexible, general, extensible solution. In this category, both the quality of resulting design and the design process are being evaluated. The design must include a detailed representation of the algorithms used (via pseudo-code, structure diagrams, etc.) that clearly illustrate the candidate's solution.

    Top-down analysis (solution decomposition) means breaking down a problem into smaller problems. These are then broken down in turn until ultimately a pseudo-code representation is obtained which can be used as a basis for program construction. it is appropriate to use diagrams for the early stages. However, for the non-standard and non-trivial modules, the final stage must be pseudo-code at a level of detail equivalent to PURE. This final state of design should lead easily into coding in an appropriate programming language. For example, an object-oriented design should be able to be coded into any one of several block-structured languages.

    This criterion refers to the documentation of the design process which does not include the final program listing. -- Syllabus 2000, page 48.

    An illustration indicating the top-down design of the solution to the problem should be produced.

    Using pseudo-code or other suitable means candidates should created an algorithmic representation of their solution. The algorithms produced should be independent of the target programming language. A programmer using almost any high-level programming language should be able to generate a computer-based solution from the submitted algorithms. Thus, it is imperative that all algorithms/subalgorithms that are essential to the functioning of the resulting program be included. -- Syllabus 2000, page 55.

    Documentation must be complete to get 4 out of 6. Furthermore, it must be portable as well to get 6 out of 6.

    IB defines complete to mean that "all the relevant decomposition from the problem definition through all stages to the final stage are included." (Syllabus 2000, page 48)

    IB defines portable to mean that "the final stage of the design can be coded into more than appropriate modular language." (Syllabus 2000, page 48)

    "Object-oriented analysis (problem decomposition) is not required by the IB syllabus, and will not be examined, but teachers using OOP programming techniques in their course will probably also want to emphasize object-oriented analysis. This is an acceptable substitute for traditional top-down design methods (function-oriented)." -- quoted from Teacher Support Material - Computer Science, For first examinations in 2000 © IBO, February 1999, page B70.

    Since UML use cases and diagrams address objected-oriented analysis, then UML diagrams are an acceptable substitute for the more traditional systems flowchart.

    Material that goes in this section includes:



    Criterion B1: Data Structures

    The student has discussed and clearly illustrated all of the data structures/types to be used to solve the problem, and provided sample data for all of them.

    Using Appropriate Data Structures was an important Syllabus criterion for 2000-2005. Here was Com Sci Gate's treatment for that period.

    Using Appropriate Data Structures 2000-2005

    Candidates should choose data structures which fully support the data storage requirements of the problem, and which allow clear, efficient algorithms to be written. They need not go beyond the requirements of the syllabus in their quest for the best data structure, nor should they make clumsy choices due to a limited knowledge of the programming language. For example, an array A[1], A[2], ... A[10] is usually preferable to the single variables A1, A2, ... A10. -- Syllabus 2000, page 49.

    Data structures that are to be used in the programmed solution to the problem should be discussed here. Some sketches/illustrations must appear in this discussion, including some sample values. -- Syllabus 2000, page 55.

    You must indicate the data structures that you used and explain why they were appropriate.

    The syllabus says that some sketches/illustrations "must appear" in this section.

    Examples of the sort of discussion that should appear are:

    • A linked list may be more appropriate than a direct access file for searching or other manipulation because the dynamic memory in which a linked list functions is many times faster than the mechanical medium of a disk drive on which a text file functions.
    • Arrays are more appropriate than atomic variables for processing related ordinal data of the same data type because you can access array data with indices.
    • Constants are more appropriate than variables for data values that do not change during execution of a program because the compiler will flag erroneous changes of the identifier.
    • Direct file access is more appropriate (faster) than sequential file access for searching and sorting because direct file access allows access with fewer necessary visits to the data.
    • A linked list is more appropriate than an array where the maximum size of the data is unknown at compile time because a linked list can change its size dynamically during execution but an array cannot.
    • C++ structs and classes are more appropriate structures than C-type structs for packaging code because C++ structures allow the programmer to control the way in which a client program or other C++ structure may inspect or modify data in the class or C++ type struct.
    • C-type strings are more appropriate than a string class for direct access file handling because the size of class strings is dynamic. All direct access file records must be the same size because the formula for locating a record depends upon every record in a file being the same size. Since C-type strings are arrays of characters of a set size, their size may be kept constant.

    To get maximum marks, IB insists that "all of the data structures that the candidate uses to solved the problem are appropriate." -- Syllabus 2000, page 49. Give a rationale for every structure used.



    Criterion B2: Algorithms

    The algorithms discussed are sufficiently logical, detailed, and well documented to be used to create the solution in Java.

    "Students must include parameters, return values, and descriptions of pre- and post-conditions." - IB Study Guide 2006, page 57

    A pre-condition is "an object's valid state and the arguments passed to a method prior to a method call."

    A post-condition is "an object's valid state and the arguments passed to a method after a method call."

    A class invariant is "an object's valid state."

    Requiring pre-conditions and post-conditions is known as Design by Contract. These are "comments" that are identified for each and every method.

    Historically, in pre-Java programming languages, pre-conditions and post-conditions were recorded as comments immediately above the signature of the function. However, with Java and especially with the use of Javadocs, Java program record pre-conditions and post-conditions as Javadocs immediately above the signatures of methods.

    Apply Javadoc taglets in your Javadoc comments, available from the University of British Columbia Computer Science 211 course. UBC uses customized Javadoc taglets for:

    • @invariant - used only to document a class or interface
    • @pre - used only to document a method
    • @post - used only to document a method

    Using Efficient Algorithms was an important Syllabus criterion for 2000-2005. Here was Com Sci Gate's treatment for that period.

    Section D: Using Efficient Algorithms for 2000-2005

    An efficient algorithm is usually one that executes rapidly and requires minimal storage (makes good use of available memory), but it could also refer to one that uses simple programming code. even though it is not faster, a loop for printing 20 numbers is more efficient than 20 print commands, because future modifications in the code will be much easier if a loop is used. Such immense inefficiencies in the code can be considered here. It is not necessary for candidates to present quantitative evidence of the efficiency of their algorithms. -- Syllabus 2000, page 49.

    To get maximum marks, IB insists that "all of the algorithms that the candidate uses to solve the problem are efficient. -- Syllabus 2000, page 49.

    Indicate the algorithms used in the program and discuss why they are more efficient than other possible less efficient algorithms. For example:

    • Select sort of a large number of data is more efficient than a binary sort because it is faster. It is faster because there are fewer comparisons.
    • Iteration is more efficient than recursion in terms of computer resources because less memory is accessed when using iteration. However, recursion is more elegant, that is more efficient in terms of the programmer's time because programmer's think more "naturally" with recursion than iteration.
    • Direct access file handling is more efficient than sequential access file handling in terms of speed but less efficient in terms of capacity because all records of a direct access file must be the same size, even when that means that a portion of some of the records is empty.

    Look up "Big-O" in the indexes of your textbooks, such as page 397 of Walls and Mirrors. The syllabus says that it is not necessary to discuss efficiency in terms of Big-O in the dossier, but is certainly appropriate to do so.

    Some online discussion of Big-O will be found by following the following links. Hit several of them and read Walls and Mirrors and you will understand this surprisingly difficult topic.

    Click HERE For IBO Direction On Criteria E, F, G and H Taken From Teacher Support Material - Computer Science ©IBO, February 1999, pages C9 - C13.



    Criterion B3: Modular Organization

    The modules discussed are sufficiently logical, detailed and well documented to be used to create the solution in Java.

    The design is assessed independently from the programming stage (stage C).

    The student may deviate from this detailed design or expand it during stage C, without penalty.

    Formative evaluation is best practice rather than summary evaluation.

    Formative evaluation is the evaluation of a design while "forming" (coding) the design. When improvements or errors are identified, both the design and code should be modified as soon as reasonably possible to enhance the program.

    Summative evaluation is the evaluation of a design after the coding is completed. Changes in design are not permitted before completion. Summative evaluation is worst practice. Much preferred, more successful and less costly is the continual correction of formative evaluation.

    First, design your program using a class diagram as best you can. Then, after the initial draft of the class diagram is designed, write source code that implements the class diagram. You often think of other classes or identify errors or improvements in design while coding.

    It is appropriate while coding to modify both the design and source code of a program, including modifying planning instruments such as a UML class diagram.

    Plans may and should be changed in light of increased experience with the problem as the project progresses. The student should practice formative and not sumative evaluaton as the project progresses. That is, everything should be constantly re-evaluated and, where doable within the time and resources available, appropriate changes should be made to both the design and implementation.

    Both types of UML class diagrams should be presented here.

    1. Class Diagram Showing Associations Only
    2. Class Diagram Detailing Attributes and Operations

    Clearly label each diagram as to whether it came during the design stage or after coding of the program was compeleted. After the coding is completed, a post-coding set of class diagrams should be included for documentary purposes.

    Design StagePost Coding
    Associations OnlyXX
    Associations, Attributes & OperationsXX

    Stage C: The Program



    Criterion C1: Using Good Programming Style

    All parts of the program listing demonstrate considerable attention to good programming style.

    Place the source code listing here. Readability and understandability are the objectives. Clarity, structure, and internal documentation determine how well this section is done.

    • Implement best practices generally and especially best Java practices in organizing and structuring the source code.

    • Finish all source code and internal documentation.

      • Ensure that all methods and classes include appropriate Javadoc comments.

      • Ensure that the documentation of all methods includes the method's purpose, preconditions and postconditions.

        To implement Javadoc in Eclipse, check out UBC's CPSC 310/352 Javadoc Tutorial: [csg HTML] [web HTML]

        To cutomize Javadoc comments to use @invariant, @pre,and @post in Eclipse, install UBC's customized taglet classes: [csg HTML] [web HTML]

      • Ensure that the beginning of every file of source code contains an identification header similar to the following.

        The program should demonstrate the use of good programming techniques. It should include an identification header indicating:

        • Program Name
        • Class/Interface name
        • Purpose of the Class
        • Author
        • IBO Candidate Number (Churchill numbers include the school's code "0130")
        • Date of This Revision
        • School
        • Computer Programming Language Used
        • Operating System Targeted
        • IDE (Integrated Development Environment) Used
        /*==========================================================================
        
          Class:    BinaryAdd                            Program:  Binary Calculator
        
          Author:   Ayebee Wannabee                IBO Candidate Number:  0001301234
        
          Purpose of Class:  Demonstrates algorithm for addition of binary numbers.
        
          Date of This Revision:  February 29, 2004        Teacher:  Gerry Donaldson
        
          School:   Sir Winston Churchill High School, Calgary, Alberta, Canada
        
          Language: Java J2SE 5.0      Target Operating System: Java Virtual Machine
        
          System:   Pentium IV 2.5 GHz running under Windows XP     IDE: Eclipse 3.1
        
        ===========================================================================*/
      • All modules (Java's methods) must be "small and clearly structured ...." (Syllabus 2000, p. 52)

      • All identifier names must be "meaningful". (Syllabus 2000, p. 52)

      • There must be a consistent indentations scheme. (Syllabus 2000, p. 52) This includes:

        • indenting about 2-3 spaces within blocks of code,
        • blank lines or a commented pattern between significant blocks of code, such as the ending of one function and the beginning of another, before the beginning and after the end of a loop, before the beginning and after the end of a switch statement, et cetera.

      • Use syntax highlighting. (Suggested but not required in Syllabus 2000, p. 52)

      • Number all lines of source code. (Suggested but not required in Syllabus 2000, p. 52)

        Most IDEs will do this but they generally do not leave the line numbers in the saved text file. To add line numbers to source code in a text file without an IDE, use Gerry Donaldson's AddNums program. You can then paste the source code your program with line numbers intact directly into a wordprocessor.

        Note: Versions of Eclipse (November, 2007) through 3.3 do not support the printing of line numbers to a printer or clip board. Copy and paste does not retain the line numbers.

        One work around is to convert the Java source code to an html or rtf (rich text file) format with a program that both generates syntax highlighting and numbers the lines of the source code. One such program that does this is Java2Html.

        I have found that rtf files retain indentation whereas html files sometimes lose the appropriate indentation. I also observed that Java2Html formated html files get inserted as tables when read into WORD and WordPerfect, but not so for rtf files. I recommend convertions to the rtf format.

        Using Java2Html, copy the rtf code into a text editor such as TextPad. Remember to tick the check box for generating "Line Numbers" and to choose "RTF" in the "Target" drop down menu before clicking the "Convert" button. Save the resulting text file with the appropriate "rtf" extension.

        The resulting rtf file retains syntax highlighting, indentation and line numbering when inserted into a current version of WORD or WordPerfect after Insert --> File....

        Caveat: Lines are not automatically renumbered if deleted or inserted in code after it has been converted. Code must be again converted by running Java2Html if lines are deleted or inserted or modified such to trigger either situation, as could happen if code were modified in the wordprocessor.


      • Print the source code.

        • Set the font size at 10 points using a non-proportional font such as Courier New.
        • Insert a footer and/or header that incorporates the file names, dates and page numbers.
        • Number pages sequentially within each section of the dossier. For example: J-1, J-2, J-3 ....
        • Use "syntax highlighting". Set font properties to emphasize different parts of syntax.
        • Set printing to wrap lines rather than truncate them, but that is the second best option. You should manually structure your code so that lines do not exceed the right margin.

    Good programming style can be demonstrated by program listings which are easily readable, even by a programmer who has never used the program. This includes small and clearly structured modules which have abundant comments, meaningful identifier names, and a consistent indentation scheme. Convoluted, confusing syntax should be avoided whenever possible. Syntax highlighting and line numbering are not required, but are encouraged if they improve readability. -- Syllabus 2000, page 52.

    The program should possess good internal documentation, including:

    • constant, type and variable declarations which should have explanatory comments
    • identifiers which should have appropriate names
    • program and subprogram names which should be easy to identify
    • classes, constructors and methods must be clearly separated and have comments for their parameters
    • suitable indentation which should be used to illustrate various programming constructs.



    Criterion C2: Usability

    The student fully documents the user-friendly features of the program, and the program meets the usability objectives in criterion A2.

    Students should pay attention to issues of usability during the design stage. To be given credit students must include features that make the program more user-friendly, such as helpful menus, help instructions, useful guidance to the user during the execution of the program.

    The features should go beyond the basic requirements needed to operate the program.

    Separate output is not required for this section. However, a usability section should be present that summarizes the features, making reference to the annotated sample runs and the program listing. Features could be annotated, commented or highlighted in those sections and a simple table presented here.

    A usability section should summarizes the features, making reference to annotated sample runs and the program listing. Features could be annotated, commented or highlighted and a simple table presented here.

    The teacher will run the program with the student before awarding achievement levels for this criterion.

    Candidates should give attention to issues of usability during the design stage. The documentation should include some explanations of the reasons for some of the usability decisions. To be given credit candidates must include features which make the program more user friendly, such as helpful menus, help instructions, useful guidance to the user during the execution of the program. These should be documented in some way, for example, if an output screen is particularly well designed for readability a hard copy should be provided and labelled as such. -- Syllabus 2000, page 50.

    Evidence of User Friendliness

    Evidence of helpful menus, instructions, etc. that will aid the user in navigating through their program must be highlighted. This can be done in the following three ways:

    • by annotating relevant parts of the hard copy output
    • by annotating parts of the program code that generate menus and instructions
    • by reproducing (cut/paste) relevant parts of the hard copy output and/or by reproducing parts of the program code that generate the menus and instructions.

    The length of this documentation will depend to a great extent on how much interaction there is between the program and the user. -- Syllabus 2000, page 56.



    Criterion C3: Handling Errors

    The student fully documents the error-handling of each input and output method within the program.

    Provide annotated screen dumps of all types of conceivable errors together with the program's response. Ensure that all screen dumps contain contextual explanations of what is happening in the screen dump. Explain the obvious, for what is "obvious" to the designer may well be invisible to the peruser.

    This refers to detecting and rejecting erroneous data input from the user, and preventing common run-time errors caused by calculations and data-file errors. Candidates are not expected to detect or correct intermittent or fatal hardware errors such as paper-out signals from the printer, or damaged disk drives, or to prevent data-loss during a power outage. -- Syllabus 2000, page 51.

    Error handling facilities can be highlighted in the following two ways:

    • by annotating parts of the program code that contain error handling routines
    • reproducing (cut/paste) parts of the program code that contain error handling routines together with the relevant parts of the hard copy output.

    -- Syllabus 2000, page 56.

    The hard copy output should demonstrate the implementation of the testing strategy. One or more sample runs should be included to show that the different branches of the program have been tested; testing one set of valid data will not be sufficient. The hard copy submitted should demonstrate the program's responses to inappropriate or erroneous data, as well as to valid data. Thus the usefulness of the error-handling routines mentioned above should become evident. While at least one complete test run must be included in the dossier, it is not necessary that the hard copy reflect every key stroke of every test run. Cutting and pasting of additional test runs can be done to illustrate the testing of different aspects of the program.

    "All test runs should be annotated in such a way that the candidate is stating what aspect of the program is being tested. Sample output must never be altered by hand, erased or covered up." (Emphasis Added)

    Sample output can be 'captured' and combined electronically with explanatory annotations into a single document. However, it is forbidden to alter or reformat sample output in any fashion (except adding page numbers or annotating in order to highlight user friendliness or error-handling facilities as discussed above), especially if these alterations would give an unrealistic impression of the performance of the program. Examples of such 'abuse' include: lining up text which was not originally aligned, adding colour or other special effects, changing incorrect numerical output, erasing evidence of errors.
    -- Syllabus 2000, pages 56-57.

    Use Exception Handling.

    Exceptions should be used for exceptional situations outside of the normal logic of a program.

    Errors likely to be fairly common should be dealt with using normal if-else type logic.

    The source code should use try{}, catch{}, and finally{} statements which include but are not be limited to:

    • RunTimeException
      • ArithmeticException
      • IllegalArgumentException
        • NumberFormatException
      • IndexOutOfBoundsException
    • IOException CHECKED
    • AWTException CHECKED

    Your program should throw an exception when it detects an exceptional problem.

    All checked exceptions must handle it in a catch{} block or throw it to the method's caller where it may be handled.



    Criterion C4: Success of the Program

    The student includes evidence that the program functions well. The student successfully achieved all of the objectives from criterion A2.


    Stage D: Documentation

    Developer's Documentation:   HTML Javadoc

    HTML (Hypertext Markup Language) is a script language used to format documents in web browsers.

    A Javadoc file is an HTML file that organizes documentation embedded in Java source code accourding to Javadoc specifications.

    Java's API Specification is posted as a Javadoc HTML file. A similar HTML file is generated when the Javadoc software tool is applied to any Java source code using appropriate Javadoc comments and taglets.

    Javadoc specifications and usage are found at Sun MicroSystem's Javadoc Tool Page.

    Any Javadoc comment may be incorporated into the Javadoc HTML file. All HTML tags are recognized and may be used as defined by Hyptertext Markup Language specifications. A table using <table>, <tr>, and <td> tags may be created. Emphasis may be added using <b>, <i>, <em>, and <strong> tags. The shape, size and colour of fonts may be controlled using the <font> tag. Line breaks may be forced using the <br> tag. Paragraphs may be isolated using the <p> .. </p> tags. Ordered lists using <ol> and unordered lists using <ul> and items within lists using <li> may be created with appropriate numbering, bullets and indentation. Et cetera, et alii, et alibi.

    Specific documentation comments are formatted in a standardized way by the Javadoc software tool. These are Javadoc taglets.

    The source code of all classes and interfaces must be preceded by the following Javadoc taglets and corresponding comments whenever appropriate.

    • @author [author name] - identifies author(s) of a class or interface in chronological order.
    • @version [version] - version information of a class or interface.
    • @link [Display Text] - inserts an explicit hyperlink to another HTML docuement.
    • @invariant - A cusomized taglet available from UBC, used only with a type (class or interface), @invariant is an assertion that is true both before and after the code is executed, but may or may not be true during the execution of the code.
    • @see [other packages, classes and interfaces] - Note containing hyperlink(s) to related classes or methods.
    • @deprecated - Note to other programmers that the class has been enhanced with new and improved features, but that older features are maintained for backwards compatibility.

    The source code of all methods and constructors must be preceded by a statement of purpose and the following Javadoc taglets and corresponding comments whenever appropriate.

    • Purpose- a clear statement of what the method does. This statement is an annotation and is not preceded by or associated with a Javadoc taglet.
    • @param [parameter name] [parameter description] - used for every paramenter in the signature of a method or constructor, listed in order of declaration, it describes what the paramenter is.
    • @throws [exception thrown] [exception description] - describes the exception that can be thrown by the method, as does @exception.
    • @exception [exception thrown] [exception description] - describes the exception that can be thrown by the method, as does @throws.
    • @return [description of return] - describes data type returned by method (unnecessary for constructors and void methods).
    • @see [other packages, classes and interfaces] - Note containing hyperlink(s) to related classes or methods, listed in order of scope, from nearest to farthest access.
    • @pre [description of precondition] - A cusomized taglet available from UBC, @pre details existing pre-conditions as known just before a method executes. IBO Syllabus 2006 (page 57) requires descriptions of pre-conditions.
    • @post [description of postcondition] - A cusomized taglet available from UBC, @post details existing post-conditions as known just after a method executes. IBO Syllabus 2006 (page 57) requires descriptions of post-conditions.

    A well documented Javadoc HTML file details the parts of the program's modules.

    A well documented Javadoc HTML file details the packages, classes, interfaces and methods of the program.

    Javadoc is a tool that parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the classes, inner classes, interfaces, constructors, methods, and fields used in the source code of a program.

    Javadoc comments and tags are entered as comments throughout a program's source code. Then, by passing the source code to the Javadoc Tool, an HTML file is generated that yields several different documented views of the program in terms of the program's attributes, constructors, methods, classes and packages.

    Further explanation and examples are found at:

    IBO requires that methods have descriptions or pre- and post-conditions of methods. Usually, when doing this, it is customary to also document the invariants of a class. Therefore Churchill students are to use the customized Javadoc taglets @pre, @post, and @invariant found at UBC's web site.

    Insert a hard copy of the Javadoc documentation. Only include documentation of classes and methods that are necessary to understand the immediate source code of the program. Include documentation of inherited classes only when that documentation significantly contributes to a better understanding of the derived classes used in the program. Use your best judgement!



    Criterion D1: Annotated Hard Copy Of The Test Output

    The student includes a complete set of annotated sample output, testing all the objectives in criterion A2.

    Including an Annotated Hard Copy of the Test Output was an important Syllabus criterion for 2000-2005. Here was Com Sci Gate's treatment for that period.

    Including an Annotated Hard Copy of the Test Output

    The hard copy of test output should demonstrate the implementation of a thorough testing strategy (as indicated by criterion E). It may not be feasible to supply sample output for every single test-case in the testing plan - indeed, a procedure may be designed to automate the testing process and may run many millions of tests. However, at least a representative sample of the test-cases must be presented as sample runs. The output should cover the entire range of test-cases (both valid and invalid data) in the testing plan, and should be presented in an organized fashion (e.g. annotated). The teacher must confirm that each candidate has actually completed the testing as claimed in the documentation. (See Vade Mecum.) -- Syllabus 2000, page 50.

    Section I: Implementing the Program [2 marks]

    Provide annotated screen dumps of "typical" test runs. Demonstrate that sequencing corresponds precisely to the original functional specifications by labelling each screen shot with the functional specification.

    Evidence here generally refers to hard copy output. Also, the design process should have been sufficiently thorough so that the resulting program has not had to be drastically restructured during the debugging phase. -- Syllabus 2000, page 52. -- Syllabus 2000, page 52.



    Criterion D2: Evaluating Solutions

    The student outlines the solution.

    • Screen dumps of JUnit tests are included and documented by attached comments. These may be console and/or GUI screen dumps.

    The student discusses the effectiveness and efficiency of the solution.

    The student suggests alternative approaches, processes and improvements to the solution and the design process.



    Criterion D3: User Documentation

    The student includes user documentation that contains clear, illustrated instructions about installing and running the program.

    State the obvious. Explicate the obscure.
    Use screen dumps everywhere!

    This is where top students blow the perfect 50. This is the user's "life line" to using your program!

    Include the following sections of your user manual as they apply. Include others that you can think of that are not stated below.

    • Cover Page
    • Table of Contents (Not of your dossier, but of this User's Manual.)
    • System Requirements
    • Installation
    • Overview
    • Features
    • Options
    • Using Help
    • How to start up
    • How to create a record
    • How to save a record
    • How to retrieve a record
    • How to change a record
    • How to shut down
    • Technical Information
    • How and from where to get updated versions
    • FAQ (Frequently Asked Questions)
    • Support (Addresses may be but do not need to be real for purposes of this dossier.) Include hours available.
      • email address (Reply within 24 hours of receipt.)
      • snail address (Reply within 2 days of receipt.)
      • phone number (7 am - 6 pm MST)
      • fax number (Reply within 2 days of receipt.)
      • ICQ# (8 am - 4 pm MST)
      • web site
    • Index (Not of your dossier, but of this User's Manual.)

    Good documentation usually includes both sample output and written instructions. It should be sufficiently complete that it will allow anyone unfamiliar with the program to start using it effectively after reading the instructions. This criterion does not refer to internal instruction. -- Syllabus 2000, page 53.

    User documentation is a simplified set of instructions designed to help end-users operate the program effectively. In terms of the hardware, this documentation should provide information concerning the minimal computer system configuration necessary. The documentation should include any information required to load, start and run the program. A user must be provided with step-by-step instructions for operating the program, being told clearly:

    • what inputs are expected during various stages of the program's execution
    • what outputs can be expected.
    -- Syllabus 2000, page 56.

    Stage E: Holistic Approach



    Criterion E1: Holistic Approach To The Dossier

    The student showed full commitment.

    The student:

    • participated fully in class discussions on dossier work.
    • took initiatives both in discussion with the teacher an/or the rest of the class.
    • took initiatives in subsequent work of a more independent nature.
    • demonstrated a full understanding of all the steps in hte development of his/her dossier.
    • demonstrated perseverance.
    • showed insight.
    • prepared well to meet deadlines set by the teacher.

    Mastery Techniques Identified [0 marks]

    Do this in a wordprocessor.

    Aspects must be "non-trivial, well documented and appropriate." (IBO Computer Science Study Guide 2006 [pdf], page 65)

    Mastery Techniques Identified must contain at least ten of the following fifteen techniques.

    1. Add data to an instance of the the RandomAccessFile class by direct manipulation ofthe file pointer using the seek method.

    2. Delete data to an instance of the the RandomAccessFile class by direct manipulation ofthe file pointer using the seek method. (Data primitives or objects may be shuffled or marked as deleted by use of a flag field. Therefore files may be order or unordered.)

    3. Search for specified data in an instance of the RandomAccessFile class.

    4. Recursion.

    5. Merging two or more sorted data structures.

    6. Polymorphism

    7. Inheritance

    8. Encapsulation

    9. Parsing a text file or other data stream

    10. Implement a hierarchical composite data structure. A composite data structure in this definition is a class implementing a record style data structure. A hierarchical composite data structure is one that contains more than one element andat least one of the elements is a composite data structure. Examples are, an array or linked list or records, a record that has one dield that is another record or an array.

    11. The use of any five standard level mastery factors - this can only be applied once. Those are:

      1. Arrays
      2. User-defined objects
      3. Objects as data records
      4. Simple selection (if-else)
      5. Complex selection (nested if, if with multiple conditions or switch)
      6. Loops
      7. Nested loops
      8. User-defined methods
      9. User-defined methods with parameters (the parameters have to be useful and used within the method body)
      10. User-defined methods with apporpriate return values (primitives or objects)
      11. Sorting
      12. Searching
      13. File i/o
      14. Use of additional libraries (such as utilities and graphical libraries not included in appendix 2 Java Examination Tool Subsets)
      15. Use of sentinels or flags

    12. - 15   Up to four mastery aspects may be awarded for implementation of abstract data types (ADTs) according to a table in the IBO Computer Science Study Guide 2006 [pdf], pages 66-67. entitled "Implementation of ACTs".

      The ADT may be implemented as a class or interface containing data members and methods appropriate to that ADT. The specific number (1, 2, 3 or 4) of mastery aspects to be awarded will depend on the thoroughness and correctness of the student's implementation.

      Floppy or CD With Source Code, Data, and Executable Files [0 marks]

      This is for Mr. Donaldson. IB only accepts hard copy (paper) evidence of your dossier.

      For now your floppy or CD must contain the following files:

      Floppy, CD or DVD Disk With All Related Dossier Files [0 marks]

      The following files are not required at this time, but they must be submitted before the end of the course. You are being informed of this now so that this knowledge might influence the way that you presently organize your files for this future assignment.

      As a requirement of Computer Science 33-IB, but not as a requirement for your IB Certificate, you will generate a web site presenting your dossier and all its files in various appropriate formats.

      The web site should organize all of the dossier files into an attractive presentation. Be creative in coming up with your own web site design. It should not be "busy". It should be simple and clear to use. An example of one such site is The Card Game Assignment by John K. Estell at Standford University.

      1. The entire dossier as submitted in the binder must be available as a single pdf document. Scan diagrams and other documents if necessary to convert to pdf Adobe's format so that they may be merged in the appropriate sequence.
      2. Javadoc file(s) of all source code.
      3. Source and data files must be in directories appropriate for successful compilation.
        • All source code must be saved as appropriate text files: *.java files.
        • All data files must be in directories as specified in the source code.
      4. Executable jar and data files must be in directories appropriate for successful execution.
      5. The executable jar and data files must be packaged in a self-installing file deployment bundle such as that created by InstallStation.
      6. All internal links must have relative addresses; not be "hard-wired" to specific directory paths.
      7. The root html file of each directory should be named index.htm or index.html.
      8. Web files should be in homogeneous directories.
        • The root directory must contain the index file: index.htm or index.html.
        • multimedia files must be organized in directories by their file type. For example, graphics files (*.gif, *jpg) must be separated from other files.
        • Source code, binary (Java byte) code and data files should each have their own root directory.


      [Counter On Strike [Home of Gerry Donaldson's Com Sci Gate]
      [Gerry Donaldson's Email Address]
      gerry@comscigate.com
      [EFC Blue Ribbon - Free Speech Online]

      URL:   http://www.comscigate.com/    Last Revised:   December 30, 2005