All HTML pages that include significant client-side or server-side code must be saved as ASP pages and must be marked with a comment in server-side code that includes:
This comment should be inserted at the top of the first section of code that appears after the <HTML> tag.
A brief description of the function of a modular section of code (e.g. subroutine, function) must appear immediately before that section, accompanied by a list of inputs to that area of code. The page itself should include a list of its inputs, as well as which pages send information to that page. (If there are no inputs, there is no need for this list.) For example:
<%
' Passage questions page (questions.asp)
' Programmer: Brian Jones
'
' Displays questions to user, one-by-one in sequential order.
'
' Inputs (from questions.asp, passage.asp):
' Request("qn") - Current question number, zero-based. Checked against
' Session("completedQuestions") dictionary to see if this
' question should be displayed again. When coming from
' passage.asp, this field will be "0", indicating the
' questions should be set up and question #1 displayed.
' Request("prevAns") - Answer to question Request("qn") - 1, if
' there is one. If coming from passage.asp, there is no
' previous answer, and none should be checked.
%>Comments among lines of code should be placed on the same side as the code; that is, if the code is server-side, the comment should be server-side, and vice-versa. Code comments should be included to increase the readability of the code. This is at the discretion of the programmer, but will be checked by the team leader.
Code itself should be formatted for ease of reading. This includes placing line breaks where appropriate (e.g. between functions, between functionally dissimilar lines of code), grouping similar functionality (e.g. into functions, subroutines), wrapping very long lines of code, choosing appropriate names for modules and variables (see below), spacing out delimiters and identifiers within lines, choosing algorithms that are easy to understand (as opposed to otherwise functionally correct or highly optimized code that is difficult to understand), etc.
Programmers should choose identifiers that best describe their functions and variables. Variable names should be in camelCasing, and should describe the contents of the variable ("previousAnswer", "questionNumber"). Function and subroutine names should be in TitleCasing and should describe what the module does ("VerifyComplete", "SqlEncode").
HTML must be clean and concise. Every paragraph must have an opening and closing paragraph tag (<P>Paragraph</P>). Proprietary tags (e.g. IFRAME and ILAYER) should be used sparingly and with cross-browser compatibility in mind, even if it is not a requirement of the project. Case of tags does not matter, so long as there's some consistency, particularly within a page. Greater-than and less-than signs must be encoded as > and <. Ampersands must be encoded as &. (A note to ASP programmers: the Server.HTMLEncode method provides these translations.)
Since the formatting of HTML code does not usually affect the appearance of a page, HTML should be formatted with line breaks and indentations that appropriately break up sections of the page and describe hierarchies of tags.
Page names should describe the function of the page to both the developers and the end-users. A page's name is not as important as its location or whatever module descriptions may be inside. The "Passage questions page" described above may justifiably be called "questions.asp" since it describes to the user his location when visiting the page, as well as to the developer what modules are inside.
Page names should be case-insensitive (preferably all lowercase) with underscores separating different words.
File extensions must match the file's type and/or purpose: ASP pages (.asp), HTML pages (.htm), include files (.inc -- typically for often-used ASP code), JavaScript (.js), HTML fragments (.htmf), the global.asa file (.asa), SSI pages (.shtm), and so on.
The software files and the modules they contain are documented below in the Software Components section.
Typically a Windows 2000 Server machine running IIS 5.0 with the FrontPage 2000 Extensions (or more recent version of same) and SQL Server 2000. The application's root folder must be configured as an IIS application.
Typically a Windows 2000 Server machine running IIS 5.0 and SQL Server 2000. The application's root folder must be configured as an IIS application.
Client machines will typically access via Internet Explorer version 4 (or later).
The structure is extremely simple for this application. Most modules follow the following pattern:
The client makes a request to an ASP page, which returns an HTML document containing input fields and/or hidden fields. When the user submits the results of a form in this document, the data is sent via an HTTP POST command to another ASP page for processing. The sequence may start over, or the second ASP file could display only links or issue an HTTP redirect after processing the data.
In this way, the entire application is structured using POSTs and redirects, as illustrated here:
Some data may be held in session variables for retrieval later. Session variables are the preferred method when data may be useful beyond the next request. The login data, for example, is held in four session variables. These variables are set by guest_login_process.asp and are later used in results.asp.
This system function enables administration of the reading passages and questions to be used in the assessment through the tables stored in the database. Specifically, the administrator can add, edit, or delete passages and questions. The administrator also can drop and create the tables in the database.
This is the root administration page and allows the administrator to access passages.asp to manage the information about the passages in the database, questions.asp to manage the questions in the database, drop_tables.asp to destroy (drop) all of the tables in the database, and create_tables_process.asp to create the tables in the database.
This page displays all information about all passages in the database and allows the administrator to add, edit, or delete information about a specific passage by directing the administrator to the passage_add.asp, passage_edit.asp, or passage_delete.asp pages respectively.
This page allows the administrator to select a passage in the database, then it displays all of the questions and answers for that passage and allows the administrator to add, edit, or delete a question and its associated answers by directing the administrator to the question_add.asp, question_edit.asp, or question_delete.asp pages respectively.
This page gives a short warning to the administrator about losing all information contained in the tables and allows the administrator to select a button that brings up the drop_tables_process.asp page, which drops the tables.
This page creates all of the tables in the database used by the software.
This page allows the administrator to fill in all of the information for a new passage and insert it into the database by posting the information to the passage_add_process.asp page.
This page shows the current information about the selected passage and allows the administrator to change it and insert the new information into the database by posting the information to the passage_edit_process.asp page.
This page asks the administrator whether to delete the passage and upon affirmation, brings up the passage_delete_process.asp page, which deletes the passage information from the database.
This page allows the administrator to create a new question and its answer choices and to specify which answer is correct. The data is inserted into the database by posting the information to the question_add_process.asp page.
This page shows the selected question and its answer choices and allows the administrator to make changes and insert the new information into the database by posting the information to the question_edit_process.asp page.
This page asks the administrator whether to delete the question and upon affirmation, brings up the question_delete_process.asp page, which deletes the question and its answer choices from the database.
This page drops all of the tables used by the software from the database.
This page adds the information posted to it from passage_add.asp about a passage to the database.
This page changes the information in the database about a passage to the posted values from passage_edit.asp.
This page deletes the information from the database that pertains to the passage specified in the post from passage_delete.asp.
This page adds the question and the choices posted to it from question_add.asp to the database.
This page changes the question and its answers in the database to the posted values from question_edit.asp.
This page deletes the question from the database that is specified in the post from question_delete.asp.
This system manages a user's session and allows the user to login and logoff. The login functionality is provided by guest_login.asp and guest_login_process.asp. The logout is carried out by abandon_session.asp
This page profiles the user for information that will be used in assessing their reading abilities and posts the data to guest_login_process.asp.
This page logs the user in, stores the user's data, and redirects the user back to the main page (index.asp).
This page logs the user out and returns them to the main page (index.asp).
This system administers the reading assessment test to the user. The start.asp page gives instructions, reading.asp presents the passage and times the user, questions.asp asks the user questions and records the user's answer, and results.asp calculates the results of the test and displays them to the user.
This page gives the user some instructions then redirects them to reading.asp to read the first passage once they are ready to begin.
This page presents the first passage when the user presses the start button and times the uses until the user presses the stop button, whereupon the passage disappears. When the user presses the take quiz button the time is posted to and the user is redirected to questions.asp to answer the first question about the passage.
This page places the reading passage time in a session variable and presents the first question. It stores the answer to the question in a session variable and then cycles to the next until there are no remaining questions in the database. Then it redirects the user to results.asp.
This page finds the results of the test and displays them to the user.
| Items |
| Complete results page. This page currently has code to determine reading ability by time, but doesn't display it according to the design document. It also does not determine reading ability by recall. |
| Create the "Evaluation of this Tool" page, whatever it is. |
| Items |
| Too many error screens; purpose of error screens misunderstood. |
| Design Component | ID | Software Component | ID |
| Guest entry screen | 2.2.2 | guest_login.asp, guest_login_process.asp | 2.2.1, 2.2.2 |
| Reading passage screen | 2.2.5 | reading.asp | 2.3.2 |
| Questions screen | 2.2.6 | questions.asp | 2.3.3 |
| Results and recommendations screen | 2.2.7, 2.3.1 | results.asp | 2.3.4 |
| Date | Name | Revision |
| 11/14/2001 | Crowell, Dunkel | Document created, Software Documentation/Code Format and Software File Names written. |
| 11/27/2001 | Crowell, Dunkel | Part of the Software Components overview written. |
| 12/02/2001 | Crowell, Dunkel | Rest of the document filled out; all sections updated and completed for first time. |
| 03/05/2002 | Galanos, Chris | Document reviewed and updated with new team member names. |