Purpose Organization Documenting Code

ballscauliflowerΛογισμικό & κατασκευή λογ/κού

30 Ιουν 2012 (πριν από 5 χρόνια και 3 μήνες)

261 εμφανίσεις


Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

Purpose
The point of these guidelines is to make it easier for other programmers and supervisors to determine
what a given program does, what objects (files, data sources, etc) belong to it, what changes have
been made, and at what point a given change was made. These guidelines will also make it easier
for you to work out how you implemented the details of your program if you have to make changes a
year later.
Organization
• Each distinct application should be placed in its own directory on the server.
• Each distinct application that uses data sources should either have its own data source or a
clearly defined general-use one.
• To the greatest practical extent, all the files for a given application, including the
documentation, should be put on one machine, in one directory structure.
Documenting Code
Headers
Each program or script file should include a header describing some basic information about it. At a
minimum, the header must include the following information:
• file name
• program name
• what application this file belongs to
• what change control number, remedy number, or other authorization the file was created under
• who originally wrote it
• when it was originally completed
• the purpose of the file
• revision history (history of changes made to this file) - Include date, person making the
modification, summary of changes, and change control/remedy number as appropriate.
• any restrictions, dependencies, or important considerations for using the file

Example header:
<!---
Application: Course-Instructor Opinion Survey (CIOS)
Change Control Number: 5142 (CIOS CONSTITUENT-REQUESTED
CHANGES FEB 2001)
Page 1 of 12


09/08/2004

Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

Module Name: student_report_options.cfm
Module Description:
Generates page to allow student to select which crn and
instructor to view survey results for.

Author: Jason Toth
Date Written: 12/5/2001
Update History:

12/20/2001 Jason Toth (jt65) (CC# 5142):
Minor changes from user acceptance testing
- Added restriction to query GetValidTermCodes to prevent students from
viewing survey results for terms prior to Fall 2001

--->
The obvious exception to the header rule are temporary files that are going to be deleted anyway and
small files whose function/use is so obvious that documentation would be redundant.

Commenting Code
For all practical purposes, you can never have too many comments as long as they are correct.
Comments are not only helpful to other developers who may have to check/maintain your code, but
are also valuable to you when you have to modify some of your older code after a year or so.
A useful technique is to pretend you have not looked at this program in one year. You no longer
remember anything about the program except what is in the file. Add enough comments so that you
can figure out what the program is doing with only the information in the program file(s).
Particularly important areas to comment are:
External resources the program needs:
<!--- Tell file-based operations what directory they should --->
<!--- write to. This should be a secure directory not readable --->
<!--- by the web server. --->
<!--- Also, do not use a trailing / in this value --->
<CFSET Variables.TempFileDir=
"/services/www/content/intranet/html/cfprod/banlogin/writeable">
If a subprogram, such as a ColdFusion custom tag (external procedure), the parameters the
subprogram uses and the rules for using them:
<!--- (REQUIRED, but can be blank) --->
<!--- the prospective date we want to check --->
<CFPARAM NAME="Attributes.StringToValidate" DEFAULT="">
<!--- (optional, values Yes/No) --->
<!--- whether we should complain if StringToValidate not present --->
<CFPARAM NAME="Attributes.Required" DEFAULT="No">
Conditions that must exist for the program to run or continue:
<!--- URL must begin with https://???.gatech.edu --->
Page 2 of 12


09/08/2004

Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

<!--- complain and abort immediately if not --->
Complex sections of code where the actions being performed (or the reasons for performing them)
are not immediately obvious:
<!--- set up stacked cookie value --->
<!--- (e.g. mainvar=value, var2=value, var3=value... ;) --->

<!--- Delete existing related_changes records (if any). Will --->
<!--- re-insert any (un)modified related_changes record(s) in next --->
<!--- step. Must do this way to cover possibility of another --->
<!--- process deleting record(s) out from under us during --->
<!--- edit/validation phase --->
Even if the module is very thoroughly commented, a brief summary is required in whatever versioning
records are kept/used. For RCS, this would mean the RCS comments used on check in.
Naming
Good naming is an important part of documentation and can actually reduce the number of comments
you need to write. It is also among the easiest ways to document.
Application Short Name
In addition to whatever official application name may exist, create a short name or acronym for the
application, such as Parking or GTASC. This name should then be used as appropriate to designate
objects that are associated with this application.
Application Directory
Among other places, the application short name should be used to name the directory the application
resides in. Since this directory name is visible to the user, this provides confirmation that they are
using the correct application and provides a form of basic grouping for documentation. The normal
expectation is that directory names should be in lower case. Talk to your team lead or project director
before using mixed or upper case names. Either way, be consistent with the use of case.
ColdFusion Templates
• The name of each template (ColdFusion page) should reflect what the template does, such as
main_menu.cfm, change_password_action.cfm, etc.
• Login pages must contain the words login or index, in accordance with standard web usage,
such as index.cfm, student_login.cfm.
• For set of pages that form a distinct logical grouping, such as the help page, options form, and
generation page for a report, consider using similar names for them. Examples:
report_cross_listed_info.cfm, report_cross_listed_options.cfm, and
report_cross_listed_generate.cfm.
• Particularly for situations where more than one application/module is housed in the same
directory, each template name for a given application/module can have the application/module
name prepended to it to indicate which files are which. Examples: peb_main.cfm,
peb_fundsummary.cfm, grants_login.cfm, grants_logincheck.cfm.
Page 3 of 12


09/08/2004

Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

• The normal expectation is that template names should be in lower case (except for
Application.cfm). Talk to your team lead or project director before using mixed or upper case
names. Either way, be consistent with the use of case.
Variables
• Variable names should be chosen carefully to make sense to both yourself and other
programmers.
• As with other names, a variable name should describe as clearly as possible what the variable
is being used for. Some examples: Student ID, EmployeeDepartmentCode,
StopCheckingFlag, InterimResultHolder
• The exact capitalization/wording style may vary according to preference, but be consistent.
• While I, J, and K are traditional names for loop counters, they should really only be used for
simple loops that do little else. For complex loops, name the counter according to its use, such
as: CurrentOutputIndex
• Variables defined in scopes other than the VARIABLES scope should include the scope name
to avoid problems and confusion. Examples: FORM.UserID,
Application.MainDataSourceName.
• Variables within the VARIABLES scope should also have the scope name defined when
necessary to avoid confusion, e.g.
<CFSET Variables.Function = Left(FORM.Function, 15)>
Data Sources
(sometimes referred to as DSNs)

• Each ColdFusion application that uses data sources should have its own data source unless
there is good reason to do otherwise. This allows the underlying database grants to be
tailored exactly to the needs of your application, which helps security.
• Except for general-purpose data sources shared by more than one application, the data source
name must include the application short name in some form.
• General-purpose data source names should clearly reflect what data is being accessed,
usually by including the database name and/or schema accessed.
• When there is any doubt, data source names must always reference which database instance
(devl, test, prod, or other) is being accessed.
• Data Source Name Examples: gtasc_devl, acctreq_userchk, dw_park_prod, grantsys_devl,
fdev75
• For program-specific data sources that use a specific database account, the account name
should begin with cf_ and include the application short name. Example: cf_appname.
• For general-purpose data sources that use a specific database account, the recommended
account name is cfuser.
Page 4 of 12


09/08/2004

Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

Queries
Again, ColdFusion query names, like cursor names, should clearly reflect what data the query gets or
its intended use, whichever makes the most sense. Examples: GetCurrentTermInfo,
CheckForDupChgRequestRecord, qCheckForDup and the following:
<CFQUERY NAME="InsureEndDateIsWithinTerm"
DATASOURCE='#FaceInstance#'>
select 'Yes' valid
from disc.term_info
where ti_term_code = '#ValidateTermCode.ti_term_code#'
and to_date('#DateFormat("#EndDateTime#", "dd-mmm-yyyy")#
#TimeFormat("#EndDateTime#", "HH:mm")#',
'DD-MON-YYYY HH24:MI'
)
between ti_term_start_date and ti_term_end_date
</CFQUERY>
Other Tags
For other ColdFusion tags that are named, such as CFLOCK and CFLDAP, the name should also
reflect what data is retrieved/sent or its intended use, whichever makes the most sense. One
example is:
<!--- lock to insure no other instance of this CF page --->
<!--- is running this SQL at the same time --->
<CFLOCK NAME="ADAMGetAndUpdateCRSeqNoLock"
TIMEOUT="3"
THROWONTIMEOUT="YES">
...
</CFLOCK>

Style
ColdFusion is case-insensitive, so thisname = ThisName = THISNAME. However, you should work
out one style of capitalizing your code and stay with it throughout the file.
ColdFusion, as a tag based language, is not quite as structured as traditional compiled languages,
but logical, consistent indention still makes your code much easier to read. Follow the standard
practice of indenting each logical level of code a certain amount. In most cases, because HTML
ignores multiple spaces, you can even do this with your output text.
The use of tabs for indention is strongly discouraged, because tabs can display as different numbers
of spaces in different circumstances. If you must use tabs to indent, use them always. Never mix
tabs and spaces for indention, as it makes the display problem much worse and makes it difficult to
change the indention of a given section of code.

Page 5 of 12


09/08/2004

Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

Maintainability and Clarity
• Use relative links wherever possible. This is also desirable for pathnames, but be careful
doing so.
• If you have a choice between a more compact way to implement something and a more clear
way, choose the more clear way unless there are overriding concerns, such as execution
speed.
• Avoid specifying optional parameters in ColdFusion tags unless they are needed for clarity. In
particular, never specify DBType in a CFQUERY.
Avoid ColdFusion-specific Issues
Always use CFLOCK tags to surround Session, Client, and Application variables. Not using CFLOCK
risks crashing the ColdFusion server. For more information, see the following Macromedia article:
http://www.macromedia.com/v1/handlers/index.cfm?id=20370&method=full
To avoid using as many CFLOCK tags, you can copy the contents of a session variable into a
corresponding variable that doesn't need locking. You can then use the corresponding variable as a
working copy. Just be sure to copy any needed changes back into the session variable before the
page completes. This technique also works for other types of variables that require locking.
Always use the SQL function to_date() and to_char(), together with the appropriate ColdFusion date
functions, when moving date values to and from a ColdFusion variable and Oracle. There are known
issues with ColdFusion's automatic date translation. The following examples show a recommended
method:
<CFQUERY NAME="InsertColdFusionDate"
DATASOURCE='#App_Main_DSN#'>
insert into example_schedule_table (
task_id,
begin_date,
end_date,
last_modified_by,
last_modified_date
)
values (
#CurrentTaskID#,
to_date('#DateFormat("#TaskBeginDateTime#", "mm/dd/yyyy")#
#TimeFormat("#TaskBeginDateTime#", "HH:mm:ss")#',
'MM/DD/YYYY HH24:MI:SS'
),
to_date('#DateFormat("#TaskEndDateTime#", "mm/dd/yyyy")#
#TimeFormat("#TaskEndDateTime#", "HH:mm:ss")#',
'MM/DD/YYYY HH24:MI:SS'
),
'#UserID#',
sysdate
)
</CFQUERY>

Page 6 of 12


09/08/2004

Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

<CFQUERY NAME="GetColdFusionDate"
DATASOURCE='#App_Main_DSN#'>
select
task_id,
to_char(begin_date, 'MM/DD/YYYY HH:MI:SS') begin_date,
to_char(end_date, 'MM/DD/YYYY HH:MI:SS') end_date,
last_modified_by,
to_char(last_modified_date, 'MM/DD/YYYY HH:MI:SS') last_modified_date
from example_schedule_table
where task_id = #CurrentTaskID#
</CFQUERY>
...
<CFSET TaskBeginDateText = GetColdFusionDate.begin_date>
<CFSET TaskBeginDate = #ParseDateTime("#GetColdFusionDate.begin_date#")# >

Security
All new applications should use secure (https) access unless there is a good reason not to.
When receiving data from a form post, even using ColdFusion, your receiving page must validate all
critical incoming data for correctness, or have other methods of assuring that critical incoming data
comes from a known-valid source. Any data that comes to one of your pages from a form post can
easily be intercepted or changed by your user.
Do not check HTTP_REFERRER as your only means of security. This value is provided by your
user's web browser and can thus be faked. The upside to this situation is that it encourages the use
of relative URLs within an application - a good thing for maintainability.
Never allow your users direct access to CFEXECUTE functionality. CFEXECUTE runs a Unix
command directly on the ColdFusion server. While this is a powerful addition to ColdFusion, this
power can result in a large security hole. If the users provide all or some input to such a command,
their input must at least be checked for invalid or malicious values.
Never allow your users to upload and run an arbitrary file without checking it first for bad or malicious
information. This is another large potential security hole.
Application files that are not to be accessed by every user may be placed in a more secure
subdirectory within the main program directory. For example, suppose program abcd was housed in
directory abcd. If the program had administrative pages that non-administrative users were not even
supposed to see, then one way to provide the additional security would be to place the administrative
pages in abcd/admin_pages (or some other appropriate name). Directory admin_pages could then
have restricted access via standard webserver methods, like htaccess/htpasswd files.
For application files that are never to be accessed directly by any user, such as CFINCLUDEd files or
those written/read from other CF files, these should be placed in their own subdirectory that is not
Page 7 of 12


09/08/2004

Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

world-readable. However, do not use the above technique with the Application.cfm file. It is location-
sensitive and is protected by the CF Server from direct access.
For more information on ColdFusion and security, see the Macromedia Security Zone at
http://www.macromedia.com/v1/developer/SecurityZone/

or Macromedia's Security Best Practices Articles and White Papers at
http://www.macromedia.com/v1/handlers/index.cfm?ID=10956&Method=Full

Presentation
ADA Compliance
All new development should follow the Access Board standards for disabled user accessibility to web
pages, more commonly known as Section 508. (Section 508 refers to Section 508 of the Federal
Rehabilitation Act of 1973, while the Access Board is the Federal Agency that sets the technical
standards for web accessibility under Section 508). Rather than reproducing the standards here, try
the following web links, or check with your project lead for more information:
The Section 508 standards with suggested techniques for following them:
http://www.access-board.gov/sec508/guide/1194.22.htm

A Section 508 standards checklist:
http://www.webaim.org/standards/508/checklist
Note that, while the Section 508 standards borrow heavily from the W3C Accessibility standards, they
are not the same. The W3C Accessibility standards are considerably stricter, but are only
recommendations. The Section 508 standards have the force of Federal law and are the ones to be
followed.
User Interface Look and Feel
Web applications, like any other, need a well-designed, consistent user interface.
The EIS PeopleSoft Web group has a standard look and feel for their applications. Web
programmers in that group are expected to follow the standard; for others it is recommended. Among
other things, the PeopleSoft group's web standard includes the following items for HTML pages:

• Both the title and the top of the page should include the application name and a page name.
• For applications where the users may be using both the training or production instance of the
application, include the database instance name. Examples: Training Database, Production
Database
• For application pages that require login, include the currently logged-in user name.
Page 8 of 12


09/08/2004

Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

The EIS PeopleSoft Web group stores all kinds of templates and common scripts in a central location.
Go to aswan for these in cfapps/cfdevl/ps_common_scripts.
An example screen shot of these items follows:



To see the complete EIS PeopleSoft Web group look and feel standard, see the following link:
http://www.grantsys.gatech.edu

Integration With Existing Applications
If a given new application is to be integrated with an existing one, such as PeopleSoft or Banner Web,
the general rule is to follow the standards that exist for that application. This includes, but is not
limited to, look and feel, security methodology, header format, and others.
Sometimes, with more loosely integrated applications, it is desirable to follow different standards than
the main application to differentiate the new work. These cases should be approved in advance by
the team lead or project director, as appropriate. In those cases, the standards in this document
should be followed instead.
Page 9 of 12


09/08/2004

Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

Performance
One rule-of-thumb says that interactive web pages should present at least some data within 2-3
seconds of accessing a page. This is not always possible, but speed is definitely desirable. Larger
reporting pages may not meet the above rule, but should be as fast as practical.
Like other database-driven languages, ColdFusion depends on the speed of your queries. Be sure all
your queries, particularly your longer queries, are reasonably fast. As many of you are aware, the
ColdFusion server can be set to return diagnostic information, including the execution time of each
query. Overly slow queries should be investigated for further tuning, indexing, a different approach,
or possibly conversion to a stored procedure.
ColdFusion is not the fastest language available, but rather a powerful one with great connectivity. If
you need very high-performance data crunching or very fine transaction control, put this logic in a
stored procedure and let ColdFusion handle the interface between it and your users. It makes the
application planning a little more involved, but works quite well.
When generating dynamic pages, consider the total size of the page you will be generating. This is
even more important if you know your application will be used via modem connections. In particular,
when populating a select box from a query, be sure the query returns a reasonable number of rows.
In most cases, a select list should have no more than 100 items and should ideally have no more
than 30. There are exceptions, but remember that a long select list takes both more time to download
and more time for the web browser to generate. This problem should also be avoided in other areas,
such as very long or heavily nested tables.

Migrations
• Currently, all developer-authored migrations are to be sent to the appropriate lead or project
director, who will double-check and forward them to the migration team. The official
mechanism for sending migration requests is the MEG application.
• Before writing the migration request, place all files to be migrated in the cfmove directory
structure that corresponds to your development directory structure. All files from previous
migrations should be deleted first. For example, if you are migrating files you developed in
cfdevl/cios/install/ddl, copy them to cfmove/cios/install/ddl.
• Before writing the migration request, insure that all directories and files have the appropriate
group name and permissions in Unix. For all ColdFusion development, all directories and files
should have group cfuser. If this needs changing, cd to the appropriate directory and run the
following Unix command:
chgrp -R cfuser *
In nearly all cases, cfm files should have permissions 644 (owner can read/write, group can
read, and others can read) Files to be kept private from the outside world, such as SQL create
scripts, should normally have permissions 640 (owner can read/write, group can read, and
Page 10 of 12


09/08/2004

Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

others can do nothing). It is very important the files at least be group-readable and set to the
correct group name so the DBAs will be able to migrate them. For more information, see Unix
File and Directory Permissions below, or run the Unix command
man chmod
(
man chmod

displays the online manual page for the command
chmod
).
• When writing the migration request, insure the machine names and paths you give are defined
completely and clearly, such as:
from: aswan: /app/cfuser/cfmove/psoft
to: sneetch: /services/www/content/intranet/html/cfprod/psoft
• When writing the migration request, all cfm and other files to be migrated should be named
explicitly. Do not use statements such as: 'Move all items in this directory'.
• When writing the migration request, if for some reason the to and from directories are not of
the same naming structure (for example, moving files from myapp/sql to myapp/install/ddl),
please indicate in the migration's comments that you are aware of this disparity and that it is
okay. If you leave this out, the migration team will possibly question the migration and halt it
until they know it is okay to proceed. Be aware that it is the team lead's responsibility to get
the information defined correctly. If the migration group does what is stated and it was not
correct, then it is the team lead's fault and responsibility to correct the problem that may have
been created.
• When writing the migration request, do not copy and paste from existing migrations or alter
existing migrations in order to save time. This process has produced far too many errors in the
past.
• When writing the migration request, make your messages extremely clear. Do not make
assumptions that the migration team knows what you want to have done. Spell it out explicitly.
• Proofread your migration request before you send it.
• Leads and Project Directors: When sending the migration request, always cc your developer(s)
and the responsible functional user(s).

Unix File and Directory permissions
Like all multi-user operating systems, Unix has a means to specify who should be able to do what
with a file. The fine details of these permissions can be rather tricky, but the basics are not hard to
learn. In Unix, to see the permissions on a given set of files, do a long directory listing (ls -l). The
listing will look something like:

{jt65@servo}:/app/cfuser/cfdevl/someapp>ls -l
total 848
-rw-r--r-- 1 gb1 cfuser 1080 Oct 9 2000 Application.cfm
-rw-r----- 1 gb1 cfuser 583 Feb 27 2001 PrivateFile.sql
-rw-r--r-- 1 gb1 cfuser 2110 Mar 16 2000 login.cfm
drwxr-xr-x 2 gb1 cfuser 512 Dec 20 1999 publicdir
drwxr-x--- 3 gb1 cfuser 512 Dec 10 1999 privatedir

Page 11 of 12


09/08/2004

Standards & Guidelines:
EIS Programming Guidelines -
ColdFusion

On the far left, you will see a series of letters and dashes, called attributes. The position of each
letter or dash is important. The first position indicates the kind of entry, with - meaning a plain old file.
The rows with d in the first position are directories (the same as folders on Windows or Macintosh
systems). After the first position are nine more positions, grouped in sets or three. The first set of
three shows the permissions for whoever owns the file/directory. The second set of three shows the
permissions for whatever group the file/directory belongs to. The last set of three shows the
permissions for other users. Web servers generally fall into the other users category, so this last set
also tells the webserver whether it should be able to show a given file/directory to the world.
After the attributes and the number, there are two more columns. The first of these give the
username that owns the file. The second of these gives the name of the group associated with the
file. In our example listing above, all the files and directories have user gb1 as the owner and cfuser
as the associated group name.
Next, what do the letters mean? For our purposes, they are reasonably self-explanatory. For files,
the letters mean:
r = file can be read and copied, but not written over
w = file can be written over
x = for special files, such as shell scripts, this means the file can be run as a program
For directories, the letters have a slightly different meaning:
r = files in directory can be read and copied
w = directory can be written into
x = directory can be searched (directory listing can be seen)
For each of the three sets, the letters are always shown in the same location. A dash in a given
position means that the permission is not given. For example, if for a file, a set shows as rwx, then
the given person can read, write and execute the file. if a set shows as r--, the given person can
read, but not write and not execute the file.
Now for some examples. Look at login.cfm in the sample listing above. Its listing shows -rw-r--r--.
The - in the first position means it is a file. The next three positions are rw-, which means the file
owner (gb1) can read and write, but not execute the file. The next three positions (second set) are
r--, which mean the group (cfuser) can read, but not write and not execute the file. The last three
positions (third set) are r--, which mean that others (people other than the owner and those in the
group) can read, but not write and not execute the file. Also, look at the listing for privatedir above. In
this case, the d in the first position indicates that this is a directory (folder). For the owner (gb1), the
permissions are rwx, so the owner can read, write, and search the directory. For the group (cfuser),
the permissions are r-x, which means that the group (cfuser) members can read and search, but not
write in the directory. Finally, the other user permissions are ---, which means that other users cannot
read, write or even search in the directory.

END of EIS PROGRAMMING GUIDELINES - ColdFusion

Page 12 of 12


09/08/2004