The Essential CL Style Guide as400network.com翻訳
www.as400network.com (ちょっとでも英語に興味のある方は、訪問してみてください。）
http://www.as400network.com/resources/artarchive/index.cfm?fuseaction=viewarticle&CO_ContentID=3067
これは、AS400Network(旧NEWS400)で、過去に掲載された、CLPコーディングスタイルのガイドです。英語中心に考えられているので、英語の小文字、大文字の話が出ています。日本では、CCSIDをファイル別に管理するのが面倒なので（慣れていないと思います）、その部分は無視してください。
なお、参考までに、英語の小文字＋半角かなを同時に使うためには、5035でソースファイルを作り、PC5250のホストコードページを939にすると、両方同時に使えます。これは、従来のように、英語の小文字の上にオーバーラップして半角かなを割り当てていたコードページを使わないで、英語の小文字、半角カナを別のコードにマッピングしているコードページを使っています。
出典：
News400 , July 1999 , pg. 66
著者：
Gary Guthrie
この方は、RPG IVや、CLPなど言語関係に大変詳しく、News400へ寄稿やMidrangeComputingのMLなどで、活躍されている有名な方です。
The Essential CL Style Guide
RPG と一緒に CL は AS/400 のためにプログラミング言語の核を形成します。したがって、
「 Essential
RPG IV 様式ガイド」 (1998 年 6 月 ) の RPG コード化スタイルガイドが CL 用の仲間のガイドを持つ事が、ふさわしいと思えます。この記事では、
私はまさしくそれを示しています :CL スタイルガイドの要点です。
なぜスタイルで煩わされるのか ?
個人的好みに対して言われていることが多くがありますが、
コードのことになると、
通常、
プログラマの数ほど、多くのスタイルを持っているのは、賢明なことではありません。 1 セットの規格に基づくただ一つのスタイルは、コードを、容易に読み、理解し、そして保守できるように、確実にするのを助けます。規格を固く守る事は、初めは、ペースを遅くしてしまうでしょうが、すぐに、それが、実際は、結果としてより早い開発となることに、気がつくでしょう。
規格を開発することにおいて、いくつかの主要な問題を覚えておくのは重要です。たとえば、我々（アメリカ人）が、大文字、小文字混在で読みなれている事実、そして、お互いに隣接するか、接近している単語に関連付けるように慣れている事実といった、心理学的な規制である。また、スクリーンのサイズなどの物理的な規制があります。始める前に、これらなどの考慮事項について考える時間を少しとれば、規格を開発する努力の結果に、
より満足するでしょう。
CL 環境のために規格を開発するとして考えるいくつかの提案を見てみましょう。これらのガイドラインを熟読するとき、
イラストについては図 1 a （別添）を参照してください。ところで、
図のサンプルコード（の内容）を理解しようとするのには、こだわらないでください -- 少し複雑ですから !
それの「見え方」に注意を払ってください。
1.0 コメント
1.1繰り返しではなく、あなたのコードを、はっきりさせるコメント。
それがそれほど時々、少なければ少ないほどよいということを思い出してください。
良いコード化のテクニックが、
あなたのプログラムをドキュメント化するのを助けますが、単にコメントでコードを繰り返すだけなら、
どんな価値も加えることはありません。
コメントを使用して、
- 簡潔なプログラム概要を提供しなさい。
- 論理的なセクションのコードを分類しなさい。
- 容易に明らかでないテクニックについて説明しなさい。
- あらゆる容易に明らかでないビジネス規則について説明しなさい。
1.2プログラムの始めにいつも簡潔な概要を含みなさい。
プログラム概要は、以下のを含むべきです。
- プログラム名
- プログラムタイプ ( 例えば、
コマンド処理プログラム、
プログラムをチェックする正当性 )
- プログラムの目的の記述
- 存在するどんな特別な情況の記述
- プログラムのインタフェースの記述 ( どんな入力、
アップデート、
および出力パラメータも )
- あらゆる特別なプログラム作成の情報
また、プログラム概要がそれぞれの変化の日付、
プログラマ、
および目的を含む変更履歴を含むべきであると言う学派があります。
もし、そうしたければ、この情報を含むことが出来るが、しかし、自分の経験からすると、しばしば無視されているか、または誤った状態になっています。あなたは、
プログラム変更を追う必要があるならば、 より良い代替手段は、変更管理システムを設けることです。
1.3 一貫した「コメント箱（図参照のこと）」を使用して、
主要なセクションのコードを分割してください。
コメントを使用することによって明確にコードのセクションを分割するには、
「コメント箱」でコメントを囲んでください。
1 行コメントか、コードと同じ行に埋め込まれているコメントを決して使用しないでください。そのようなコメントは、
うっかり見落とされる傾向があります。そして、それらはしばしば乱れた外観になります。
代わりに :
- 1 桁目からコメントを始めなさい、そして、それらを標準の長さにしなさい。
- 箱のスタイルの階層構造を使用しなさい。例えば、等記号 (=)
から主要なセクション箱をつくり、（図 1 の F のように）まだ別のレベルのものをもっているならば、ハイフン (-)
からの下位のレベルの箱（図 1の G が使っている第 3 の箱のスタイルのように）を、下位のレベルに置きなさい。通常、
2 つの箱のスタイルで十分でしょう。
空白行を使用して、 関連するコードを分類して、
読み易さを高めてください。
コメントが不要ですが、 まだコードのセクションを分割していたいという場合、
空白行は役に立つ場合があります。正しい場所で使用されて、
余白はまた、
あなたのコードを読むのをより簡単にします。
2.0 ステートメント整列
唯一のよくレイアウトされたコメントは、 CL プログラムに、スタイルを追加する、最初の一歩です。また、（コマンドの）プロンプタがステートメントを並べる方法を、改良をすることにで、コードにおける CL ステートメントの読み易さを最大にすることも出来ます。
2.1 ほぼ左のマージンでステートメントを開始しなさい。
2 桁目にラベルを設定するために、
プロンプタは 14 桁目からステートメントを始めます。代わりにラベルをそれら自身の行に左に移して、
1 桁目からそれらを始めてください。 3 桁目から CL コマンドを始めなさい ( または、もしコードが DO 構造の一部または、前の行の構造か継続ならば、適切なインデントレベルから開始をしなさい ) 。
2.2 最大のコマンドの長さにスペースを充てて、コマンドパラメータを並べてください。
コマンドが 10 バイトよりも短いときに、最大の長さを埋めるために、コマンドの後に十分な空白を残してください。さらにもうひとつ、スペースをスキップして、そして、
次に、
最初のパラメータを始めてください。たとえば、コマンドが 3 桁目で始まるとき、
14 桁目から最初のパラメータを始めてください。
2.3 インデントを使用して、
従属関係を強調してください。
インデントしたいすべてのステートメントに、
一貫したインデントの要素 ( 私は 2 つのスペースが好きですが ) を使用してください。それぞれのネストレベルに対しては、この要素でインデントを増やしてください。
2.3.1 IF ステートメント。
IF ステートメント自身で、一行毎に、に各々の IF 条件を書き込んでください。 ( または、条件が *AND か *OR を使用するならば、マルチステートメントで書き込みなさい。継続行では、もし、 IF 条件が「真」のときに、実行されるコマンドは、インデントにしてください。
1 つのコマンドだけがテストの結果として実行されるなら、 DO グループとともに IF を続けないでください。代わりに、
実際のコマンドを実行するように記述しなさい。ひとつの IF ステートメントが、 ELSE ステートメントと関連付けられているときは、 IF と ELSE
を整列させてください。図 1 の C 、 D 、および H におけるコードのセグメントは、これらのガイドラインを例証しています。
2.3.2 MONMSG/EXEC ステートメント。
MONMSG(Monitor Message) コマンドの EXEC
パラメータを使用するとき、図 1の B のように、それが MONMSG に続く行に指定される、エラーの場合に実行されるコマンドを、字下げする整列規格にしたがってください。図では、
MONMSG の EXEC パラメータと初めの括弧は右マージンに置かれ、終わりの挿入句もまた、その後の行の右マージンに置かれます。あなたが単に EXEC キーワードを削ることができると良いのですが、あいにく、そのキーワード必須です。このように、邪魔にならない EXEC とその括弧を置くことによって、コードの読み易さをさらに高められます。
このスタイルに従うよりも、数人のプログラマは、右マージンに置く代わりに、 MONMSG コマンドの近くで EXEC キーワードを置くのを好みます。
2.3.3 DO グループ。
ひとつの DO グループの DO と ENDDO の間に存在する各ステートメントをインデントしなさい。このように、行をグループにすると、どのステートメントがどの DO グループに属するのかすぐにわかります。
2.4 コマンドパラメータの整列。
多くの場合、コマンドとそのすべてのパラメータを 1 つの行に、収めることができます。これが可能でないときに、
コマンドとともに、最初のパラメータをその行に置きなさい。それぞれのその後のパラメータのために継続行をコードしなさい、そして、
最初のものの直接下で、それを並べてください。継続キャラクタ (+) を、コメント箱の最後の文字の右に置きなさい。
2.5 1 つの繰り返された行コマンドには、コマンドとそれらのパラメータを整列しなさい。
いくつかのコマンド ( 例えば、
CHGVAR 、
DCL) は、しばしば、連続して繰り返され、ただ一つの行に収まります。そのような場合、コラム (A) のように、コマンドとそれらのパラメータを並べてください。
2.6 それぞれの行の終わりに、一貫したカラム位置で、継続キャラクタを並べなさい。
このスタイルは、きちんとした外観をあなたのプログラムに与えるだけでなく、
どのコマンドが、その後の行の上で続けられるのか、を区別するのが容易になります。
そしてちょっと見ただけで、そのコマンドは継続されているのか、わかります。もはや、継続キャラクタを探して、狩をしたり、そこらをたたきまわる使命は無くなります。
3.0 変数名と大文字小文字
様々なプログラミング実体のために、多くの学派が、変数命名、や、大文字、小文字、または大文字小文字混在に関して存在する。
適切な変数命名と適切な大文字小文字の使用は、コードの外観と読み易さを大いに高めます。
3.1 変数名における特殊文字を避けてください。
いくつかの理由で変数名における特殊文字 ( 例えば、
$ 、
#) を避けるのは賢明です。まず最初に、
特殊文字は言語から言語まで異なることができます。そして、ソフトウェアが異なった、または、多重言語の機能があるシステムで走るならば、それらの使用は、問題を引き起こし得るのです。また、特殊文字は、うまく「読む」ことが出来ません。 Cst# よりも CstNbr( または、
CstNo) の方が解釈するのが簡単ではないでしょうか？同様に、フィールド名が表示ファイルからのものという事実などの情報を意味するように、特殊文字をあるフィールド名の前に置かないでください。
DspCstNbr か DspCstNo は、 $Cst# よりも読みやすいだけではありません。「 $ 」よりむしろ「 Dsp 」という接頭語は、フィールドが表示ファイルから来ると、より明確に述べていることに成ります。
3.2 意味のある変数名を構成しなさい。
必要なら、特定の実体を表すために略語を頼った、命名規定について工夫しなさい。そして、これらの略語を結合して、意味のある変数名を構成しなさい。 OS/400 コマンドは、その verb/subject
構文で、このタイプの構造の好例を提供しています。図 1はある他の例を示す。
3.3 大文字小文字混在を使ってください。
すべて大文字を決して使用しないでください !
それは、読書するのに、
恐らく最も難しいケーススタイルです。このスタイルガイドがすべて大文字で示されるならば、
あなたはこの文を読んでさえいでしょう -- とうの昔にあきらめたでしょう !
同様に、すべて小文字のコードは、解釈するのが困難な場合があります。
数人のスタイリストが、 変数に対しては、すべて小文字を使い、その他の何もかものためには、すべての大文字を使用すると提唱しています。他の人は、他の異形を提案します -- このための大文字、それのための小文字、他の何かのために大文字、小文字を混ぜたというように。しかし、あなたの目標は、読み込み可能なコードを作成することであり、変数は、変数であるという事実を強調することでは、ありません。そもそも、あなたは、それが変数であることを知っているのです！
私は、 すべてに対して大文字小文字混在を使用することを提案します。このように書かれているコードはきちんとしているように見えるし、断然、最も読みやすい。実体を多数の略語に分解するとき、
それぞれの断片 ( 例えば、
command string に対する変数 &CmdStr) の最初のキャラクタだけを大文字で書きなさい ;
名前が 1 つの要素だけから由来するとき、
まさしく名前 ( 例えば、
user に対する変数 &User) の最初のキャラクタを大文字で書いてください。
4.0 近道の Dos と Don'ts
近道には、プログラムコードにおけるそれらの役目がありますが、必ずよく考えて使用してください。
手初めに、不精から近道を決して使用しないでください。この傾向は品質の低下の確かな徴候です。また一方では、
いくつかの近道が、品質を落とさずに、
実際に CL プログラムを読みやすくするパーツを作ることが出来ます。
4.1 連結演算の（速記）シンボルを使用しないこと。
CL の *CAT 、
*BCAT 、
および *TCAT 連結オペレータのために速記シンボル
|| 、
|> そして |< を使用するのを避けなさい。
この垂直なバーキャラクタ (|) は、いくつかのキーボードマッピングにおいては、容易には、使えないものです。
もっとも、より重要なことには、予約語よりも、これらのシンボルの意味は明確ではありません。
4.2 明白なキーワードでコマンドを簡素化しなさい。
いくつかのコマンドは明白なキーワードを持っていて、全体でキーワードを省略しても、
より解釈しやすいものです。
4.2.1 PGM を簡素化すること。
PGM(Program) コマンドに関する
PARM キーワードを無くしなさい、そして、
括弧で、パラメータリストを囲んでください。
4.2.2 DCL を簡素化すること。
DCL(Declare CL Variable) コマンドのときに、
キーワード、 LEN 、
および VALUE 、
VAR 、 TYPE
、を落としてください。
位置決めでキーワード値を定義し、そして、
LEN と VALUE パラメータを括弧でくくってください。
括弧の間の LEN が可能な最も大きい値
(4 桁の数字、
１スペース、
および 2 つの小数部の桁
) を含むのを可能にすることができるくらいのスペースを残してください。
図 1は A
でこの規則を例証しています。
4.2.2 MONMSG を簡素化すること。
MONMSG コマンドの MSGID
キーワードを削り、そして、括弧を使用して、
モニターしているメッセージ ID
のリストをくくってください（ B
）。
4.2.3 CHGVAR を簡素化すること。
CHGVAR(Change Variable) コマンドの
VAR と VALUE
キーワードを省略しなさい、そして、
括弧で、 VALUE パラメータをくくってください。
4.2.4 IF を簡素化すること。
IF ステートメントからキーワード
COND と THEN
を削り、そして、上で与えられた整列ガイドラインに従ってください。
4.2.5 ELSE を簡略化すること。
ELSE コマンドの CMD
キーワードを削りなさい、そして、
上に与えられた整列ガイドラインに従ってください。
4.2.6 GOTO を簡素化すること。
GOTO コマンドの CMDLBL
キーワードを削ってください。
5.0 種々雑多な提案
他のいくつかの一般的なテクニックが、
CL プログラムをより読みやすく、維持できるようにするのを助けることができます。
ここに、
いくつかのアイデアがあります :
5.1 初めの括弧の直後、後りの括弧の直前に、空白を挿入してください。
この規則は平凡に見えるかもしれませんが、
それはあなたのコードを読むのをより簡単にします。
5.2 標準のエラー処理ルーチンを開発してください、そして、あなたのコードの終わりに置きなさい。
異常終了からあなたのユーザを隔離するのは賢明なことです。
終わりのほうに、いつもプログラムの標準のエラー処理いルーチンを入れるべきです。どんな予期しない誤りも捕まえるために、グローバルな
MONMSG ステートメントを使用しなさい。そして、エラー処理セクションで優雅にエラーを制御してください。
5.3 値を参照する前に、
「多重の値」変数からただ一つの値を抽出してください。
ひとつの変数が、限定された物の名やデータ構造の内容など、
1 つ以上の値を含むとき、
あなたのプログラムでそれらを使用する前に、
個々の値を抽出してください。個々のフィールドを宣言し、そして、次に、フィールドを抽出するために組み込み関数
%SST と共に CHGVAR
コマンドを使用してください (E)
。そして、
あなたのプログラムにおけるこれらの個々のフィールドを使用してください。
2001-6-21
| 
