| Prev | Chapter 12. Engineering Standards | Next |
|---|
By Michael Yoon and Aurelius Prochazka
-</authorblurb> - -+
To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas: -
- -+
Usually we organize our files so that they mainly serve one of the following three purposes: -
+displaying objects and their properties
manipulating or acting on objects in some way (by creating, editing, linking, etc)
housing procedures, packages, data models and other prerequisite code +Essentially, we want our files named in a fashion that reflects their purpose.
-
displaying objects and their properties
manipulating or acting on objects in some way (by creating, editing, linking, etc)
housing procedures, packages, data models and other prerequisite code -Essentially, we want our files named in a fashion that reflects their purpose.
- Under the page root: -
- -For naming files that enable a specific action on an object, use this format:
- --+
For naming files that enable a specific action on an object, use this format:
- --
object-verb.extension-+
For example, the page to erase a user's portrait from the database is
-/admin/users/portrait-erase.tcl. -However, modules typically deal with only one primary type of object - +
However, modules typically deal with only one primary type of object - e.g., the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on. Example: the user pages for the Bookmarks module live in the
-/bookmarks/directory, and so there is no need to name the bookmark editing page with a redundant url:/bookmarks/bookmark-edit.tcl. Instead, we omit the object type, and use this convention: --+
- --
verb.extension-+
Thus, the page to edit a bookmark is
-/bookmarks/edit.tcl. -For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:
- --+
For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:
- --
one.extension-+
For example, the page to view one bookmark is
-/bookmarks/one.tcl. Note that no verb is necessary for display-type files. -Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:
- --+
Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:
- --
object.extension-+
For example, the page to view the properties of an ecommerce product is
-/ecommerce/product.tcl. -For naming files in a page flow, use the convention:
- - - -- - -
foobar.extension(Step 1)
foobar-2.extension(Step 2)...
foobar-N.extension(Step N)+
For naming files in a page flow, use the convention:
foobar.extension(Step 1)
foobar-2.extension(Step 2)...
foobar-N.extension(Step N)where
- -foobaris determined by the above rules. -+
Typically, we use a three-step page flow when taking user information: -
- - -- -
Present a form to the user
Present a confirmation page to the user
Perform the database transaction, then redirect
Put data model files in
/www/doc/sql, and name them +
Present a form to the user
Present a confirmation page to the user
Perform the database transaction, then redirect
Put data model files in
- -/www/doc/sql, and name them for the modules towards which they are used: -- --+
--
module.sql-+
In the Tcl library directory: -
- -For files that contain module-specific procedures, use the -convention:
- --+
- -
For files that contain module-specific procedures, use the +convention:
--
module-procs.tcl-For files that contain procedures that are part of the core ACS, -use the convention:
- --+
For files that contain procedures that are part of the core ACS, +use the convention:
--
ad-description-procs.tcl-
File names also appear within pages, as linked URLs and
form targets. When they do, always use abstract
URLs (e.g., user-delete instead of
user-delete.tcl), because they enhance maintainability.
-
+
Similarly, when linking to the index page of a directory, do not
explicitly name the index file (index.tcl,
index.adp, index.html, etc.). Instead, use
@@ -152,71 +67,40 @@
(/top-level-dir/). If linking to the directory in which
the page is located, use the empty string (""), which
browsers will resolve correctly.
-
Include the appropriate standard header in all scripts. The first line should be a comment specifying the file path relative to the ACS root directory. e.g. -
- -
+- -
# /www/index.tcl -+
or -
- -
+- -
# /tcl/module-defs.tcl -+
For static content files (html or adp), include a CVS identification tag as a comment at the top of the file, e.g. -
- -+<!-- file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp --> -- -+
In addition, all static HTML files, documentation and other pages should have a visible CVS ID stamp, at least during development. These can be removed at release times. This should take the form of a line like this: -
- -+<p> Last Modified: file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp </p> -- -+
This can be at the top or bottom of the file. -
- - -Using ad_page_contract
- -+
For non-library Tcl files (those not in the private Tcl directory),
use ad_page_contract
after the file path comment (this supersedes set_the_usual_form_variables and
ad_return_complaint). Here is an example of using
ad_page_contract, which serves both documentation and page input
validation purposes:
-
+# www/register/user-login-2.tcl ad_page_contract { @@ -234,15 +118,9 @@ {return_url {[ad_pvt_home]}} {persistent_cookie_p f} } -- - - -+
Salient features of ad_page_contract:
-
A mandatory documentation string is the first argument. This has +
A mandatory documentation string is the first argument. This has the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the received variables and any necessary explanations.
The second argument specifies the page inputs. The syntax for switches/flags (e.g. multiple-list, array, etc.) uses a colon (:) followed by any number of flags @@ -262,20 +140,13 @@ QQvariables, which were automatically created by ad_page_variables and set_the_usual_form_variables. The use of bind variables makes such previous variable syntax obsolete. -
Using ad_library
- -+
For shared Tcl library files, use ad_library after
the file path comment. Its only argument is a doc_string in the
standard (javadoc-style) format, like
ad_page_contract. Don't forget to put the @cvs-id in
there. Here is an example of using ad_library:
-
+# tcl/wp-defs.tcl ad_library { @@ -284,17 +155,9 @@ @author John Doe (jdoe@example.com) @cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp } -- - -Non-Tcl Files
- -+
For SQL and other non-Tcl source files, the following file header structure is recommended: -
- - -+-- path relative to the ACS root directory -- -- brief description of the file's purpose @@ -303,33 +166,18 @@ -- created -- -- $Id$ -- - -+
Of course, replace "--" with the comment delimiter
appropriate for the language in which you are programming.
-
Construct the page as one Tcl variable (name it
page_content), and then send it back to the browser with
one call to doc_return, which will call
db_release_unused_handles prior to executing ns_return, effectively
combining the two operations.
-
+
For example: -
- - -+set page_content "Page Title] <h2>Page Title</h2> @@ -351,11 +199,7 @@ [ad_footer]" doc_return 200 text/html $page_content -- - - -+
The old convention was to call ReturnHeaders and
then ns_write for each distinct chunk of the page. This
approach has the disadvantage of tying up a scarce and valuable
@@ -368,26 +212,11 @@
first, so that the user is not left to stare at an empty page while
the query is running.)
-
+
Local procedures (i.e., procedures defined and used only within one
page) should be prefixed with "module_" and
should be used rarely, only when they are exceedingly useful.
-