| 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
@@ -67,40 +152,71 @@
(/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 { @@ -118,9 +234,15 @@ {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 @@ -140,13 +262,20 @@ 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 { @@ -155,9 +284,17 @@ @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+
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 @@ -166,18 +303,33 @@ -- 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> @@ -199,7 +351,11 @@ [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
@@ -212,11 +368,26 @@
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.
-
($Id$)
+ +