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.

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.

• 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.

• 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

• In the absence of any other type of documentation such a user’s manual, print out all the pages of the help file. This will provide documentation for the application.

• Inspect literally every menu going from left to right, taking and saving screen shots of every menu as you go, giving them meaningful file names for later identification. This ensures that, as a first pass, you will at least inspect all menus in the application.

  Going left to right is not entirely arbitrary as that is the pattern of writing and reading script of European languages. Given an European author of the application, and in the absence of any other indication, it seems more probable than not that left to right is the pattern of either the importance or logical sequence of functionality.

• Read each screen shot into PaintShop Pro, crop the portion that you want to analyze and comment upon, save it as a graphic (WordPerfect graphic if using the WordPerfect wordprocessor), and read it into your wordprocessor.

  Analyze and write a description of each function listed in the menu. It often pays to enter trial data into a related dialog box, take a screen shot of that dialog box, crop it in PaintShop Pro, insert it into your wordprocessor and used it to enhance the function’s description.

• Peruse the application’s web site for further commentary by the author and for sufficient information to give a citation reference. Then compose the reference for your dossier’s "Works Cited" list while you have ready access to the application and author’s web sites.

  Always give a full bibliographic reference for the source of the applications, web sites or other works that you quote or otherwise reference.

  Excellent links to standard conventions for citing sources will be found on ComSciGate.com (left )index frame at: [Java Programming] --> [Documentation] --> [Citing Sources]. Some of the pages to these links no longer exist.

  The APA (American Psychological Associateion) Style Manual is one of the most respected such standards in the world. This is the format for citations that is expected from Churchill Computer Science dossiers. When citing electronic references, refer to http://www.apastyle.org/elecref.html. When citing non-electronic sources, APA Style still applies.

• The review of the first instance of a type of software application should be thorough and complete so that a researcher can get a very complete “lay of the land” of that “genre” of application.

  The first review then, should be as “typical” of the genre of software being researched as possible so that the researcher can then establish a “main line” set of specifications that most applications of that genre would or could or should incorporate.

  The second review of an application of the same or similar genre can then be viewed primarily for differences between it and the first application. The first application is deemed, somewhat arbitrarily, as the “main line” because it was the first frame of reference for that genre of application.

  Noted differences between the first two applications may then supplement the “main line” of specifications that were observed for that genre of application.

  Successive reviews of applications of the same genre would then continue to be used to supplement or inform or enhance the quantity and sophistication of appreciation of specifications that an application of that genre has, could have or should have.

• 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.

• C2: Usability

• C4: Success of Program

• D2: Evaluating Solutions

  • Plan JUnit Testing here. JUnit Testing must be implemented to satisfy Criterion A3: Prototype Solution.

    You may use pseudocode, stubs, or class diagrams to plan JUnit Testing.

    • For every class of the program, there must be a corresponding JUnit testing class.

    • For every significant method in every class of the program, there must be a corresponding JUnit testing method. There need not be JUnit testing methods for trivial methods, such get( ) and set( ) methods.

    • Be specific about which JUnit assert methods will be used, including actual parameters.

Stage B: Detailed Design

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

Stage C: The Program

• 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

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:

• North Carolina State University's Javadoc Tutorial describes Javadoc Templates in Eclipse and how to generate an HTML Javadoc document in Eclipse.

• Deitel's pdf document Creating HTML Documentation with javadoc presents a thorough explanation.

• A brief but clear tutorial for a couple of courses offered at the University of British Columbia, CPSC 310/352, briefly explains Javadoc documentation and how to generate the Javadoc HTML file from Eclipse.

• Using Custom tags with Javadoc and Eclipse for invariants, pre-conditions and post-conditions is also explained by the UBC web site.

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!

• Algorithmic Success: State and/or show that all JUnit tests corresponding to the final source code passed without failure.

• State and/or show that algorithms were observed to have satisfactory, anticipated Big-O measures.

Stage E: Holistic Approach