サンプルアプリケーションの使用ガイドライン
目的
プログラミングで重要なのは、開発者が一貫したコーディング方法を取ることです。しかし、これはつねに同じ方法でアプリケーションを作成すべ きだという意味ではなく、プログラマーがロボットのようにすべてを機械的に処理すべきだという意味でもありません。むしろ、作成するアプリケーシ ョンごとに独自の必要条件があり、それぞれの環境に応じたコーディング方法を採用することが重要です。 ここに記載されている使用ガイドラインは、『ファーストステップ』にある 2 つのサンプルアプリケーションと併用するために特別に作成されました。 サンプルアプリケーションには推薦されるさまざまな方法が多く含まれていますが、とくに、以下の点が重要です。 ¨ アプリケーションとコードを探究する開発者の教育 ¨ 教育と参照情報に関する説明 ¨ 正しく理解するための秩序と一貫性 ¨ 簡単にコードをコピーし、開発者自身のアプリケーション内で再利用するための方法 このガイドは、どのようにサンプルアプリケーションが構築されたかを理解するためのものです。 重要: このガイドは新しいアプリケーションを作成するための教本ではありません。サンプルアプリケーションは上記の目的を前提に作成されまし た。ご自身のコーディングガイドラインを作成するための足がかりとしてお考えください。このガイドは『ColdFusion MX Coding Guidelines』(http://livedocs.macromedia.com/wtg/public/coding_standards/contents.html) のダイジェスト版です。ガイドライン
以下のセクションで、ColdFusion サンプルアプリケーションのネーミング、形式設定、および、プログラミングの規則を説明します。ネーミング規則
以下のネーミング規則が変数に適用されます。 ¨ 名前は英語で読める単語もしくは句にします。 ¨ 名前は小文字で始め、大文字も混用できます (たとえば、firstName)。 ¨ アンダースコア文字は使用するべきではありません。 ¨ 一般的に、名前は略書きするべきではありません。この規則には URL 変数も含まれます (たとえば、custServ の代わりに customerService を使用)。この規則の例外は単語「identification」です (たとえば、userID)。¨ わかりやすくするために、ブール値を is で開始します (たとえば、isEmployee)。 ¨ 変数名に他の接頭辞を使用するべきではありません。わかりにくくなります (たとえば、aEmployees、stEmployees、qEmployees などを避ける)。 以下のネーミング規則がデータベースと SQL に適用されます。 ¨ データベースと SQL ステートメントで使用されるすべての名前は、一貫性および大文字小文字を区別するデータベースとのポータビ リティのために、すべて大文字にします。 ¨ わかりやすくするために、アンダースコアで単語を区切ります。データベースと SQL の外ではアンダースコアは使用するべきではありませ ん。大文字と小文字を利用してください。 ¨ テーブル名は複数形で説明的にします (たとえば、EMPLOYEES)。ただし、テーブルに 1 行のデータしか含まれていない場合は、 単数形で説明的な名前を使用します。 ¨ 列名は単数形で説明的にします (たとえば、FIRSTNAME や FIRST_NAME など)。 ¨ 列名内にテーブル名を繰り返すべきではありません (ただし、列名をよりわかりやすくする場合を除く)。
¨ プライマリキーは、「ID」を後に追加したテーブル名の単数形にします (たとえば、EMPLOYEEID や EMPLOYEE_ID など)。 ¨ 名前の略書きすべきではありません。
ファイル名には以下の規則が適用されます。 ¨ HTML ファイルの末尾には .html が付きます。 ¨ CFML ファイルの末尾には .cfm が付きます。 ¨ CFC (ColdFusion コンポーネント) の末尾には .cfc が付きます。 ¨ ColdFusion カスタムタグの末尾には .cfm が付きます。 ¨ XML ファイルの末尾には .xml が付きます。 ¨ すべてのファイル名は小文字にします。アンダースコア文字で単語を区切ります。この規則の例外は Application.cfm と OnRequestEnd.cfm で、このとおりに大文字と小文字を使用する必要があります。 ¨ カスタムタグのネーミングには小文字とアンダースコア文字を使用します。 以下のネーミング規則が CFC に適用されます。 ¨ コンポーネント名は大文字で始め、小文字を混用できます (たとえば、ShoppingCart)。 ¨ メソッドとプロパティは小文字で始め、大文字を混用できます (たとえば、checkOut)。 ¨ CFC メソッドへのパスは、ファイル名とメソッドと完全に一致させます (たとえば、ShoppingCart.checkOut)。
HTML と CFML の形式設定規則
以下の形式設定規則が HTML と CFML に適用されます。 ¨ タグとその属性を小文字で書きます。 ¨ 等号 (=) をスペースで囲んではいけません。 ¨ 属性値をつねに二重引用符で囲みます。 ¨ 属性値に二重引用符がある場合は、それを一重引用符で囲むことができます。その逆も可能です。 ¨ ファイル名のような特殊な規則が優先される場合を除き、属性値を小文字で書きます。 ¨ 必要に応じて、16 進法の色をナンバー記号 (#) で使用し、エスケープします。以下のコードは、テーブル用のテーブル行 (tr) タグ 内で使用される 16 進法の色、および、適切な形式設定を「字下がり」で示します。 <table border="0" cellpadding="0" cellspacing="0"> <tr bgcolor="#999999"> <td valign="top" align="right"> <img src="shared/images/companyLogo.jpg" width="300" height="100" /> </td> </tr> </table> ¨ ColdFusion 関数は小文字で始め、大文字を混用できます。 ¨ ビルトイン ColdFusion 演算子 (is、and、or、not) を小文字で書きます。 ¨ ColdFusion タグや関数内では、ナンバー記号 (#) を変数の前後に使用すべきではありません (ただし、属性値内では使用できま す)。以下のコードは、さまざまな ColdFusion コードの形式設定を示します。 <cfif compareNoCase(variables.companyName, "Macromedia")> ... </cfif> <cfset firstName=queryname.firstName /> <cfquery name="employeeSelect" datasource="#request.dsn#"> ... </cfquery> ¨ CFC を以下と同じように形式設定します。 <cfcomponent hint="..."> <cffunction name="checkOut" returnType="boolean" hint="・><cfargument name="cart" type="struct" hint="・ /> <cfset var cartInsert="" /> <cfset var isSuccessful=true /> <cftry> <cfquery name="cartInsert" datasource="#request.dsn#"> ... </cfquery> <cfcatch type="database"> <cfset isSuccessful=false /> </cfcatch> </cftry> <cfreturn isSuccessful /> </cffunction> </cfcomponent> ¨ SQL クエリを以下のスタイルと大文字小文字で形式設定します。 SELECT FIRSTNAME, LASTNAME FROM EMPLOYEES WHERE EMPLOYEEID = <cfqueryparam cfsqltype="cf_sql_numeric" value="#url.employeeID#"> AND DEPARTMENTID = <cfqueryparam cfsqltype="cf_sql_numeric" value="#url.departmentID#"> INSERT INTO EMPLOYEES (FIRSTNAME, LASTNAME, DEPARTMENTID) VALUES ( <cfqueryparam cfsqltype="cf_sql_varchar" value="#form.firstName#"> , <cfqueryparam cfsqltype="cf_sql_varchar" value="#form.lastName#"> , <cfqueryparam cfsqltype="cf_sql_numeric" value="#form.departmentID#"> ) UPDATE EMPLOYEES SET FIRSTNAME = <cfqueryparam cfsqltype="cf_sql_varchar" value="#form.firstName#"> , LASTNAME = <cfqueryparam cfsqltype="cf_sql_varchar" value="#form.lastName#"> , DEPARTMENTID = <cfqueryparam cfsqltype="cf_sql_numeric" value="#form.departmentID#"> WHERE EMPLOYEEID = <cfqueryparam cfsqltype="cf_sql_numeric" value="#form.employeeID#"> DELETE FROM EMPLOYEES WHERE EMPLOYEEID = <cfqueryparam cfsqltype=”cf_sql_numeric” value=”#form.employeeID#”> 形式設定規則には次のような例外があります。 ¨
cfset タグ属性値を二重引用符で囲む必要はありません。ほとんどが変数であるためです。文字列の場合は、二重引用符を使
用します。ファイル構造の規則
¨ メインアプリケーションを以下のファイル構造内に格納します。使用するアプリケーションの名前を appname が指し、ルートの ColdFusion ディレクトリ (普通は c:\cfusionmx) を cfmxroot が指すことに注意してください。
{cfmxroot}/wwwroot/appname/ {cfmxroot}/wwwroot/appname/db {cfmxroot}/wwwroot/appname/extensions {cfmxroot}/wwwroot/appname/extensions/components {cfmxroot}/wwwroot/appname/extensions/customtags {cfmxroot}/wwwroot/appname/extensions/includes {cfmxroot}/wwwroot/appname/webroot {cfmxroot}/wwwroot/appname/webroot/images {cfmxroot}/wwwroot/appname/webroot/shared {cfmxroot}/wwwroot/appname/webroot/shared/css {cfmxroot}/wwwroot/appname/webroot/shared/js
wwwroot ディレクトリと webroot
ディレクトリがあります。普通、サーバー管理者は異なるアプリケーションを指すためにサーバ ー上のドメイン名を転送します。この例では、ドメイン名は webroot を指します。ここにすべての CFM ページとイメージが格納 されます。この方法の利点は、extensions (components、customtags、includes) とデータベースが webroot ディレクトリ内 になく、外部からの攻撃がより少ないために、より安全であるということです。 ¨ カスタムタグパスを ColdFusion MX 7 Administrator に登録する必要があります。 {cfmxroot}/wwwroot/appname/extensions/components ¨ appname_includes という ColdFusion のマッピングを作成します。これは次の位置を指します。 {cfmxroot}/wwwroot/appname/extensions/includes ¨ アプリケーションごとにデータベースファイルを次のフォルダに置きます。 {cfmxroot}/wwwroot/appname/db ¨ アプリケーションサブディレクトリをアプリケーションディレクトリ内に置きます。 {cfmxroot}/wwwroot/appname/webroot/reports/ ¨ 共有リソースを shared ディレクトリ内に置きます。 {cfmxroot}/wwwroot/appname/webroot/shared/images/ {cfmxroot}/wwwroot/appname/webroot/shared/documents/ {cfmxroot}/wwwroot/appname/webroot/shared/css/ {cfmxroot}/wwwroot/appname/webroot/shared/js/ ¨ Web サービスまたは Macromedia Flash Remoting としてアクセス可能な CFC (たとえば、cffunction タグがaccess="remote" を指定) を、共有リソース内に格納します。
{cfmxroot}/wwwroot/appname/webroot/shared/css 既に定義されているwebroot ディレクトリへの仮想マッピングがこのパスをアクセスするために使用されます。
¨ 他のすべての CFC を Web ルートディレクトリの外に格納します。{cfmxroot}/wwwroot/appname/extensions/components このフォルダにあるコンポーネントを、適切なサブフォルダに格納します。
コーディング規則
以下の規則が CFML によるプログラミングに適用されます。 ¨ すべての変数をスコープし、そのスコープを小文字にします (たとえば、url.variablename)。 ¨ グローバル変数を Application.cfm ファイル内でリクエストスコープされた変数として設定します。 <!// Requestscoped 変数はページプロセスの間ずっと保持されます。そのため、「グローバル」なアプリケーション変数に使用するとよ いでしょう。Application.cfm ファイルに格納して、ページプロセスのすべてにそれが見えるようにしてください。 //> <! set datasource name created in the ColdFusion Administrator > <cfset request.dsn="HumanResources"> <! set absolute path to documents directory > <cfset request.documentPath="c:\cfusionmx\wwwroot\intranet\shared\documents"> ¨ ブール値をつねに true か false として記述し、1 や 0 を使用するべきではありません。 ¨ ブール値を他の値に対してテストするべきではありません。 <cfif isEmployee> ... </cfif> NOT <cfif isEmployee is "true"> ... </cfif> ¨ 複数の値に対して 1 つの例外を評価する際に、cfif タグの代わりに cfswitch タグを使用します。 ¨ 重要なコードや外部サービス (データベース、メールサーバーなど) を呼び出すコードの周りに、つねにエラートラップを含めます。 ¨ cflock タグを使用する場合は、競合状態 (2 つのリクエストが同じデータを同時にアクセスしたり更新したりすること) を避けるための みに限定します。 ¨ CFC の場合は、つねに cfargument タグのタイプ属性を指定してください。値 any の使用を避けてください。 ¨ すべての CFC は、インスタンスを初期化する init() と呼ばれるメソッドを定義します。メソッドはコンポーネントに一致する戻りタ イプを持ち、空ではなく this を返します。次の例は cart.cfc という名前の CFC 用です。 <!// これ以上は返さなくても、必ずすべてのコンポーネントに init() メソッドを使用してください。そうすることにより、Java のような他 の言語で達成された以下の適切なコーディングに従うことができます。詳細は、「コンストラクタ」の情報を参照してください。 //> <cfcomponent hint="Shopping cart component"> <cffunction name="init" access="public" returnType="cart" output="false"> ... arguments as necessary ... ... perform initialization ... <cfreturn this /> </cffunction> </cfcomponent> ¨ CFC を呼び出す方法を 1 つ選択してください。<!// コンポーネントを呼び出す方法がいくつかあります。次のコードで行われているように、cfobject タグと cfinvoke タグを使用 するのも 1 つの方法です。また、オブジェクトの作成と、次のような 1 つのステートメントにまとめた init() メソッドの呼び出しも参 照してください。 <cfset cfcCart = createObject("component","cart").init() /> //> <cfobject component="cart" name="cfcCart" /> <cfinvoke component="#cfcCart#" method="init" returnvariable="cfcCart" /> <cfinvoke component="#cfcCart#" method="update" returnvariable="isSuccessful"> ... </cfinvoke> ¨ 開始と終了モードの両方ですべてのカスタムタグを実行することを予想します。 <cfswitch expression="#thisTag.executionMode#"> <cfcase value="start"> ... </cfcase> <cfcase value="end"> ... </cfcase> ¨ クエリキャッシュを使用するとパフォーマンスが向上しますが、サンプルアプリケーションの複雑な部分のみに限定します。初心者の場合 は、クエリを単純なままに残します。 ¨ cfqueryparam タグを使用すると、クエリパフォーマンスが向上します。 <cfquery name="employeeSelect" datasource="#request.dsn#"> SELECT FIRSTNAME, LASTNAME FROM EMPLOYEES WHERE EMPLOYEEID = <cfqueryparam cfsqltype="cf_sql_numeric" value="#form.employeeID#"> </cfquery> ¨ クエリ結果が大きい場合は、cfquery タグの blockFactor 属性を適切に使用すると、クエリパフォーマンスが向上します。 ¨ compareNoCase() 関数を使用して、2 つの値を比較できます。この関数は、値が一致すると 0 を返します。そのため、is not に対応します。 <cfif compareNoCase(url.employeeID, 10)> ¨ listFindNoCase() 関数を使用して、1 つの項目をリストに比較できます。 <cfif listFindNoCase(employeeList, "10")> ¨ リストの代わりに配列を使用しますが、単純な比較の場合は、わざわざリストを配列に変換する必要はありません。 ¨
cfmodule タグを使用してカスタムタグを呼び出してはいけません。その代わりに、カスタムタグのファイル名をファイル拡張子なしに
接頭辞の cf_ を付けて使用し (たとえば、cf_tagname)、既に定義済みのカスタムタグパスに格納されているカスタムタグにア クセスします。 ¨ サンプルアプリケーションが同じカスタムタグ名を使用する場合は、cfimport タグと相対パスを使用して、それらを呼び出します。 ¨evaluate() function の使用をなるべく避けます。
caller["var_" & i] variables["var_" & i]¨ structFind(structure, key) の代わりに、つねに structure.key か structure[key] を使用します。 ¨ x=incrementValue(x) の代わりに、つねに x=x+1 を使用します。
コメント規則
コード内でコメントを書く際に、以下の規則が適用されます。 ¨ 可能な限り、ColdFusion コメントを使用します。 ¨ 各ファイルをページに関するコメントセクションで始める必要があります。以下はその例です。 <!// Author: Emily Kim ([email protected]) Creation Date: 06/03/04 Copyright: (c) 2004 Macromedia, Inc. Purpose: to display one Employee’s detailed information. Input: employeeID (required) Revision Log: 6/04/04 – ekim – modified display formatting. //> ¨ この『ファーストステップ』の目的はサンプルアプリケーションを学習の指針として使用することですから、コードを長い説明でコメントしま す。 ¨ 論理的な分析が必要ではない場合でも、形式を分析してコメントします。 <html> <head> <title>Getting Started Experience</title> </head> <body> <! start logo table > <table border="0" cellpadding="5" cellspacing="0"> <tr> <td> <img src="shared/images/logo.jpg" width="200" height="100" /> </td> </tr> </table> <! end logo table > <! start main content table > <table border="0" cellpadding="5" cellspacing="0"> <tr> <td> Some text here. </td> <td> <! start nested table for form > <form action="form_action.cfm" method="post"> <table border="0" cellpadding="5" cellspacing="0"> <tr><td align="right"> First Name: </td> <td> <input type="text" name="firstName" size="20" /> </td> </tr> <tr> <td align="right"> Last Name: </td> <td> <input type="text" name="lastName" size="20" /> </td> </tr> </table> </form> <! end nested table for form > </td> </tr> </table> <! end main content table > </body> </html> ¨ 条件的論理を説明するために、コメントを自由に追加してください。
¨ ColdFusion の cfcomponent、cffunction、cfargument タグを使用する場合は、hint 属性を完成させます。
XHTML 準拠
ColdFusion タグと HTML タグの両方とも、可能な限りこの規則に従います。例外は cfelse、cfset、cfmodule タグです。 ¨ 要素と属性名には小文字を使用する必要があります。 ¨ 空ではない要素の場合は、終了タグが必要です (たとえば、<p>paragraph text</p>)。 ¨ 空の要素の場合は終了タグが必要か、開始タグが /> で終了する必要があります。スラッシュの前に必ずスペースを置いてください (たとえば、<br />)。 ¨ 属性値をつねに二重引用符で囲む必要があります。508 準拠
サンプルアプリケーションにアクセスして書く際に、以下のガイドラインが適用されます。 ¨ 生成されるすべての HTML は 508 条のアクセシビリティ基準を満たします (http://www.macromedia.com/macromedia/accessibility/508_guidelines.html と http://www.section508.gov/index.cfm?FuseAction=Content&ID=12#Web を参照)。 ¨ すべての非テキスト要素と同等のテキストを、alt、longdesc、要素コンテンツのいずれかで供給します。 ¨ マルチメディアの表示と同等の代替手段を、表示と同調します。 ¨ すべての色付きの情報を色なしでも使用できるように Web ページを設定します (たとえば、コンテキストやマークアップなど)。 ¨ 関連スタイルシートなしでも読めるように文書を構成します。 ¨ 冗長なテキストリンクを、サーバーサイドイメージマップのアクティブな領域ごとに供給します。 ¨ サーバーサイドイメージマップの代わりにクライアントサイドイメージマップを供給します (ただし、使用可能な幾何学的形状で定義でき ない領域を除く)。 ¨ 行と列のヘッダーをデータテーブル用に指定します。¨ データテーブルに複数の行ヘッダーか列ヘッダーの論理レベルがある場合は、マークアップを使用して、データセルとヘッダーセルを関連 させます。 ¨ 識別とナビゲーションを容易にするようなタイトルをフレームに付けます。 ¨ 画面が 2～55 Hz の周波数で点滅する原因とならないようにページを設定します。 ¨ 他の方法がない場合は、Web サイトがこの条件に従うように、同等の情報または機能を持つテキストのみのページを供給します。 元のページが変更された場合は、必ずこのテキストのみのページの内容を更新します。 ¨ ページが内容を表示する場合、または、ページがインターフェイス要素を作成するためにスクリプト言語を使用する場合は、スクリプト が供給する情報を、補助的技術により読み込まれる機能的テキストで指定します。 ¨ Web ページの内容を解釈するためにアプレット、プラグイン、または、他のアプリケーションがクライアントシステム上に存在する必要が ある場合は、1194.21(a) ～ (l) 条に準拠するプラグインかアプレットへのリンクをページ上に供給します。 ¨ 電子フォームをオンラインで完成するように設計する場合は、利用者が補助的技術を使用してフォームの完成と送信に必要な情報、 フィールド要素、機能などにアクセスできるフォームにします (すべての指示とキューを含む)。 ¨ 反復されるナビゲーションリンクを利用者がスキップできるようなメソッドを供給します。 ¨ タイムドレスポンスが必要な場合は、利用者にそのことを警告し、時間延長が必要なことを表明できる十分な時間を与えます。
