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.
%>
Internal documentation comments 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.
Elsewhere, 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, concise, and designed for compatibility across Internet Explorer and Netscape Navigator. Every paragraph must have an opening and closing paragraph tag (<P>Paragraph</P>). Proprietary tags should be used sparingly and with cross-browser compatibility in mind. Case 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.
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.
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.
Not currently described in the requirements, but typically a Windows 2000 Server machine running IIS 5.0 and SQL Server 2000.
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:
<Description of the system function and an overview of how the software components accomplish it. Diagrams may be useful.>
<The purpose of the component and a bulleted list of steps that this component accomplishes.>
| Items |
| Complete results page. |
| Complete internal documentation. |
| Create the "Evaluation of this Tool" page, whatever it is. |
| Items |
| Too many error screens; purpose of error screens misunderstood. |
No design document yet.
| Design Component | ID | Software Component | ID |
| Date | Name | Revision |