ColdFusion in Context: Design 1

This tip will help you "connect the dots" easily, automatically extract documentation from your code, give you more secure user sessions, and avoid "cookie not found" errors.

Proposed Directory Approach

• Leave as few documents in the top directory of the application as possible: typically a global variables page, the home page, and a page for unplanned exit such as a database error. This reduces the number of points of attack that require separate protection; it also reduces confusion.
• **Put everything else in directories exactly one level below the top directory, protected appropriately by Application.cfm for that directory. This way, any routine can call another with ../directory_name and always knows that the few pages in the top directory are exactly one level up. Server mappings aren't needed within the application, and its easy to incorporate pages and navigate between pages. If it's in your function, get it directly. If it's not, get it from ../another_directory.
  • This is a simple, yet powerful technique. Many large organizations have a relatively flat organizational chart, relying on policy rather than direct supervision to get things done. Code can work the same way.
• Put all database access pages in one directory to be included as desired. This way, they're easy to find and easy for Application.cfm in that directory to block their direct use. Application.cfm can be set to redirect all direct browse attempts to the home page, yet the pages can be included in other pages without difficulty.
• Put all file access pages in one directory to be included as needed. Ditto.
• Put all stock display pages (such as global title bars) in one directory. Ditto. Use this approach for anything to be shared.
• Create a directory for each logical function such as login, account access, billing, inventory [grin], to divy up the workload, simplify role-based access, and make things easy to find.
• That's it.

Proposed Page-Level Comment

• On every page, put a page-level ColdFusion comment consisting of a short description and decision points. Automated documentation tools can figure other aspects of the code, but this information is needed to understand what the code is intended to do in the first place and can help both before and after the page is fully written.
• A sample short description is written in the third person and looks like this:

  . checks login, verifies credentials,
  . and sends the browser
  . to the appropriate page.
  

• An automated documentation tool would already know the filename, can readily find and concatenate lines that begin with a period, and can therefore readily use this input to produce a statement that looks like this:

  "gate.cfm checks login, verifies credentials, and sends the
  browser to the appropriate page."
  

• A sample set of decision points for this page looks like this:

  ; bad login: login.cfm
  ; no access: login.cfm
  ; admin access: admin/menu.cfm
  ; user access: work/menu.cfm
  

• Express the conditions of decision points - the left-hand side - in a notional way, indicating function rather than specific variable names. This way, they'll be understandable by the customer and will survive fits of variable renaming. Code comments can optionally refer to these notional terms if desired. For example, an if statement might be followed by a comment naming one of those notional conditions (e.g., "admin access") if it seems useful to do so.
• That's it. Any line whose first non-white space character is a period followed by a space becomes part of the page-level description in documentation; any line whose first non-whitespace character is a semicolon followed by a space can be listed by a documentation tool as a decision point for that page. (Formatted this way, the tool could even find them buried in code where decisions take place, but you'll probably want to put them near the top of the page where humans will look for them first.)

Proposed Browser Credentials

• Except when browsing unprotected or login pages, require the browser to present additional information (such as the encrypted accountID of the account currently using that session). This reduces the likelihood that someone will break in by finding a valid cfid/cftoken combination, thereby hijacking an on-line user's session. (Closed sessions can't be hijacked.) If the browser doesn't return the right encrypted accountID for the session, access will be denied.
• That's it.

Proposed Cookie Approach

• Set cookies in a fashion that causes them to go away when the browser closes. This way, your users won't have to be paranoid about them.
• In general, use cookies for user identification and credentials, not for passing application data between pages. This way, an overloaded connection is less likely to drop or cache data that should be complete and timely. This way, you won't accidentally send more cookie data for your domain than the browser can handle and experience the "joy" of having the browser drop data randomly, without warning.
• That's it.

Application