PHPの仕様-PHPチュートリアル-php.cn

元のテキストがどこから来たのかを確認する方法はなく、インターネットからいくつかの変更が加えられたとしか言えません。仕様全体は少し長いですが、後半のいくつかの提案は非常に良いと思います。

PHP プログラミング標準

1. 命名標準

1.1 変数

1.1.1 グローバル変数

グローバル変数は、$g_data_list など、$g_ で始まります。

1.1.2 一般変数

一般変数は小文字で名前が付けられ、単語の区切りにはアンダースコアが使用されます。

変数名には名詞、または形容詞+名詞を使用してください。 $value、$new_value など。

1.1.3 一時変数

ループ内で頻繁に使用される$i、$jなどの一時変数は他の目的で使用しないでください。

1.2 関数

関数名は、最初の単語の最初の文字を小文字にしてキャメルケースで命名され、アンダースコアなどの接続子は禁止されています。

getUserImg() などの関数に名前を付けるときは、動詞 + 名詞を使用することをお勧めします。

一連の関数を完成させる関数をファイルに配置し、その関数を格納したファイルの名前をname.func.phpとします。

1.3 クラス

クラスはキャメルケースを使用して名前が付けられ、最初の単語を含む単語の区切りには英語の大文字と小文字が使用され、PageManager のようにすべての単語の最初の文字は大文字になります。 class はファイルに対応します。

いくつかのクラスが密接に関連している場合、それらを 1 つのファイルに格納できます。

クラスを格納するファイルの名前は ClassName.class.php です。

1.4 メソッド

メソッドは、getCurrentPage() のように、英語の大文字と小文字を単語の区切りに使用します

where2go( など）。 );

一般的に使用される略語を使用する場合は、getHtml() のように最初の文字のみを大文字にします。

2. 書式規則

2.1 意味上の分離

関数とメソッドの間には空行間隔を使用する必要があります

同じ関数内の密接に関連するステートメント間では改行は必要ありませんが、それ以外の場合は改行が必要です。

2.2 スペースのルール

2.2.1 論理演算子の前後にはスペースが必要です

正: $a == $b;

誤: $a==$b;

$a ==$b;

正：$a++; $a--;

誤：$a++; $a --;

注意：加算演算子と減算演算子ではスペースを追加できません。

2.2.2複数のパラメーターを分離するためにスペースを使用する必要があります。オフオフの ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐ ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ = 0; $i エラー: for($i = 0; $i

2.3 文字列と変数の接続規則

文字列と変数の接続には、「.」記号を使用する場合、「.」記号の前後にスペースを追加する必要があります。変数の前後に「{}」

正解: $my_name = 'file_' . $var1;

エラー: $my_name = "file_'.$var1 ;

$my_name = "file_$var1";

2.4 括弧の規則

括弧内の関数名の後にスペースや構文キーを追加する必要はありません、単語の後の括弧の後にはスペースが必要です。

正解: for ($i = 0; $i < 10; $i++)

strlen($my_name);

誤: for($i = 0; $i < 10; $i++ )

strlen ($my_name);

2.5 中括弧のルール

中括弧は上部と下部に対応している必要があります。

正:

if ($a)

If ($a){

$b = $a;

}

2.6 配列の定義規則

配列を定義して使用するときは、一重引用符を追加する必要がありますキー値の前後。

PHPコード：

正解：

$user_info = array(

'name' => '',

名前のハンドル => '',

性別 => ''

);

echo $user_info[name];

2.7 SQL ルール

PHP に埋め込まれた SQL ステートメントのキーワードはすべて大文字です。テーブル名とフィールド名はバックティック (`) で囲む必要があります。フィールド名のスペースによるエラーを防ぐため、データ値は両側を一重引用符 '' で囲む必要があります。 SQL インジェクションを防ぐために、データ値はエスケープされています。

正解: $sql = "SELECT `user`.`name` FROM `user` WHERE `id` = '{$id}' LIMIT 1";

エラー: $sql = "select name.user from name where id = {$id} ";

備考: Sqlite は ''' をサポートしていません。一重引用符エスケープは、次のように一重引用符の前に一重引用符を追加することです: "''a"

3. コメントのルール

3.1 一般規則

コメントはロジックをうまく説明できない場合にのみコードを補足するために使用し、コメントはプログラムの一部として扱い、コメントの作成/保守と同時に記述してください。コード;

コメントは、API レベルのドキュメントの生成での使用を容易にするために、PHPDocumentor の仕様を完全に使用します。

3.2 詳細ルール

PHPDocumentorのマニュアルを参照してください。各部位のアノテーション例を以下に示します。

3.2.1 著作権情報

アノテーション名著作権情報

アノテーションデモ //

// +-------------------------- -----------------------------+

を通じてを通じて -------------- ------------------------+

// | Copyright (c ) 2000-2003 Joshua Eichorn -------- ----------------------------------+

// このソースファイルは PHP ライセンスの対象です |

// +---------------------------------------------------------- ----- ----------+

備考: PHPDocumentor のページレベルの DocBlock との競合を避けるために、著作権情報をマークするには // を使用します

3.2.2 ファイルヘッダーのコメント例

コメント名ファイルヘッダーcomment

コメントデモ

PHPコード：

/**

* インラインタグのすべての抽象表現はこのファイルにあります

* @package phpDocumentor

* @subpackage InlineTags

* @version 1.2以降は別ファイル

* @version $Iドル

備考：

1 ファイルヘッダコメントの指定が必要属するパッケージとサブパッケージ

2 in @version 追加CVS によるファイル管理を容易にする $ID

3.2.3 クラスアノテーションの例

アノテーション名クラスアノテーション

アノテーションのデモ

PHP コード:

/**

* この要素は、{@}link} のような {@}インラインタグ} を表すために使用します

* @see parserStringWithInlineTags

* @package phpDocumentor

* @subpackage InlineTags

* @author Greg Beaver

* @since 1.0rc1

* @version $Revision： 1.21.2.6 $

* @tutorial inlinetags.pkg

3.2. カテゴリ 4.属性アノテーションの例

アノテーション名クラス属性アノテーション

アノテーションのデモ

PHPコード:

/**

* 要素の型

* 型は

の手間を省くために多くの関数で使用されます

* @var string

var $type = 'inlinetag';

3.2.5 関数/クラスメソッドのアノテーションの例

アノテーション名関数/クラスメソッドのアノテーション

アノテーションのデモ

PHPコード:

/**

* @return string always ''

* DocBlock

の短い説明を計算します

* @see parserStringWithInlineTags::getString()

* @see parserStringWithInlineTags::trimmedStrlen()

function getString()

。クラス名が提供する手がかりに基づいてクラスが何であるかをまだ思い出せない場合は、設計が十分ではありません。

3 つ以上の単語で構成される名前が混在すると、システム内のさまざまなエンティティ間で混乱が生じやすくなります。設計を見て、その名前に対応するエンティティに非常に多くの機能があるかどうかを確認してください。

派生クラスに名前を付けるときは、その親クラスの名前を使用する誘惑を避けるべきです。クラスの名前はそれ自体にのみ関連しており、その親クラスの名前とは何の関係もありません。

サフィックス名が役立つ場合があります。たとえば、システムがエージェントを使用している場合、実際に情報を送信するコンポーネントに「ダウンロードエージェント」という名前を付けます。

4.2 メソッドと関数の名前付け

通常、各メソッドと関数はアクションを実行するため、その名前付けは、何をするのかを明確に示す必要があります: errorCheck() の代わりに checkForErrors() を使用し、 dataFile() を置き換える dumpDataToFile() を使用します。そうすることで、関数とデータがより区別しやすいオブジェクトになります。

サフィックス名が役立つ場合があります:

Max - エンティティに割り当てることができる最大値を意味します。

Cnt - 実行中のカウント変数の現在値。

キー - キーの値。

例: RetryMax は最大再試行回数を表し、RetryCnt は現在の再試行回数を表します。

時には接頭辞が便利です:

は - 何かについて質問することを意味します。 Is を見るたびに、人々はそれが問題であることがわかります。

Get - 値を取得するという意味です。

Set - 値を設定することを意味します

例: IsHitRetryLimit。

4.3 略語にはすべて大文字を使用しないでください

いずれの場合でも、以下の状況に遭遇した場合は、略語を表すためにすべて大文字を使用する代わりに、最初の文字を大文字にし、残りの文字を小文字にすることができます。

by getHTMLStatistic.

理由：

）名前に頭字語が含まれている場合、人々は非常に異なる直感を持つようです。ネーミングの意味が完全に予測できるように、統一した規則を設けることが最善です。

networkABCKey の例を考えてみましょう。C は ABC の C なのか、キーの C なのかに注意してください。気にしない人もいれば、嫌う人もいます。したがって、コードごとに異なるルールが表示されるため、それを何と呼ぶべきかわかりません。

例:

class FluidOz // FluidOZ

と書かないでください

class GetHtmlStatistic // GetHTMLStatistic

と書かないでください

4.4 クラスの名前付け

単語の区切り文字として大文字を使用し、その他の文字はすべて小文字を使用します

最初の文字を使用します名前の大文字の文字の文字

intin in in in in in in in in in in in in in in in in my name ..ほとんどの人がこれが最良の方法だと思います。

例:

class NameOneTwo

4.5 クラスライブラリの命名

現在、異なるメーカーやグループのクラスライブラリ間のクラス名の競合を避けるために、名前空間がますます広く採用されています。

名前空間がまだ採用されていない場合は、クラス名の競合を避けるために、クラス名の前に一意の接頭辞を追加するのが一般的です。もちろん、それ以上の文字を使用する方がよいでしょう。

例:

John Johnson のデータ構造クラスライブラリには、次のように Jj をプレフィックスとして付けることができます:

class JjLinkList

{

}

もう 1 つの妥協策は、クラスライブラリ (実際には Java) を含むディレクトリを作成することです。これも行われます)、異なる名前空間を表すために異なるディレクトリを使用します。

例:

Microsoft のデータベース関連のクラスライブラリは、次の場所にあります:

/classes/com/Microsoft/ Database/DbConn.php

Apache のデータベース関連のクラスライブラリは、次の場所にあります:

/classes/ org/apache/ Database /DbConn.php

4.6 メソッドの名前付け

関数名には英数字のみを含めることができ、アンダースコアは使用できません。数字は使用できますが、推奨されません。

。関数名に複数の単語が含まれる場合、最初の単語以外はすべて大文字になります。これは一般に Camel のルール (「studlyCaps」または「camelCaps」) として知られています。コードの可読性を高めるために、名前にある程度詳細かつ長い名前を付けることができます。 singlyは常に「Get」または「Set」から始まります。コードの一部を削除し、どのデザインパターンが使用されているかが一目でわかるようにします。この仕様では、静的クラスにパッケージ化する必要があるグローバル範囲を持つ関数 (つまり、オブジェクトからの関数) を許可していません。

4.7 クラス属性の命名

属性名には文字「m」を接頭辞として付ける必要があります。

接頭辞「m」の後には、クラス命名に関する一貫したルールが続きます。

「r」で始まることが参照を示すのと同様に、「m」は常に名前の先頭を修飾します。

理由:

「m」接頭辞は、クラス属性とメソッド名の間の競合を防ぎます。メソッド名とプロパティ名は、特に要素にアクセスする場合によく似ています。

例:

class NameOneTwo

var $mVarAbc;

var $mErrorNumber;

var $mrName;

4.8 Namメソッド内のパラメーターを指定する

最初の文字には小文字を使用します。

最初の文字以降のすべての単語は、クラスの命名規則に従って最初の文字が大文字になります。

理由:

メソッド内の一般的な変数を区別できる。

名前の競合を引き起こすことなく、クラス名に似た名前を使用できます。

例:

Class Nameonetwo

{

Function Startyourengines

各単語の境界点として '_' を使用します。

理由:

このアプローチにより、コード内の変数の範囲が明確になります。

すべての変数はコード内で異なって見えるため、簡単に識別できます。

例えば

function handleError($errorNumber)

getTimeOfError();

$error_processor = OsErr->getErrorProcessor() ;

}

4.10 参照変数と関数の戻り参照

参考文献には接頭辞を付ける必要があります'r'

理由:

異なる型の変数を識別しやすくするため

どのメソッドが変更可能なオブジェクトを返し、どのメソッドが変更不可能なオブジェクトを返すかを決定できます。

例:

function &rStatus() {};

}

4.11 グローバル変数

グローバル変数は接頭辞 'g' を付ける必要があります。

理由

変数のスコープを知ることは非常に重要です。

例:

global $gLog;

global &$grLog;

4.12 名前付き定数/グローバル定数を定義する

グローバル定数は各単語を「_」で区切ります。

理由

これは、グローバル定数に名前を付ける伝統です。他の定義と矛盾しないように注意する必要があります。

例:

define("A_GLOBAL_CONSTANT", "Hello world!");

4.13 静的変数

静的変数には接頭辞「s」を付ける必要があります。

理由:

変数のスコープを知ることは非常に重要です。

例:

function test()

{

static $msStatus = 0;

}

4.14 関数の名前付け

関数名はすべて CGNU の規則に従って小文字を使用し、で区切ります。 '_ ' 言葉。

理由:

これにより、関連するクラス名を区別しやすくなります。

例:

function some_bloody_function()

{

}

4.15 エラーリターン検出ルール

エラーを無視したくない場合は、すべてのシステムコールでエラーメッセージを確認してください。

include の各システムエラーメッセージのシステムエラーテキストを定義します。

5.記述ルール

5.1 中括弧 {} ルール

3 つの主要な中括弧配置ルールのうち、2 つが許容され、そのうちの 1 つ目が最良です:

キーワードの周囲に中括弧を配置します以下の同じ列内:

if ($condition ) while ($condition)

末尾括弧はキーワードと同じ列にあります:

if ($condition) { while ($condition) {

どちらの方法でも問題ありませんが、ほとんどの人は前者を好みます。その理由は、心理学の研究と研究の分野にあるものです。

前者を好む理由は他にもあります。使用する文字エディターが括弧一致をサポートしている場合 (vi など)、最も重要なことは適切なスタイルを持つことです。なぜ？大規模なプログラムがあり、この大規模なプログラムがどこで終わるのかを知りたい場合に、このように言います。最初に開始括弧に移動すると、ボタンを押した後にエディターが対応する終了括弧を見つけます。例:

if ($very_long_condition && $second_very_long_condition)

else if (...)

{

. ..

}}

あるプログラムブロックから別のプログラムブロックに移動するには、カーソルと一致するキーを使用するだけで、一致する括弧を見つける必要はありません。

5.2 インデント/タブ/スペースのルール

インデントにはタブを使用します。

各レベルのインデントには 3 ～ 4 つのスペースを使用します。

必要に応じてインデントする方法はもう使用しません。インデントレベルの最大数に関する固定ルールはありません。インデントレベルの数が 4 または 5 を超える場合は、コードを除外することを検討できます。

理由:

多くのプログラマーがタブをサポートしています。

あまりにも異なるタブ標準を使用すると、コードを読むのが非常に難しくなります。

非常に多くの人がインデントレベルの最大数を制限しようとしますが、通常、それが仕事とは見なされません。私たちは、プログラマーがネストの深さを賢明に選択すると信じています。たとえば、funce（）

括弧と関数名を近づけないでください。

必要な場合を除き、Return ステートメントでは括弧を使用しないでください。

理由:

キーワードは関数ではありません。関数名とキーワードを括弧で囲んでいると、その 2 つが 1 つであることが簡単にわかります。

例:

if (条件)

strcmp($s, $s1);

return 1;

5.4 オブジェクトにピンを付ける実際の作業はアーキテクチャ関数で行う

しないオブジェクトアーキテクチャコンストラクターでの実際の作業。コンストラクターには、失敗しない変数の初期化や操作が含まれている必要があります。

理由:

コンストラクトはエラーを返すことができません。

例:

class Device

};

$dev = new Device;

if (FAIL == $dev->Open()) exit(1);

5.5 If then Else Format

レイアウト

これはプログラマが決めます。ブレースのスタイルが異なると、外観も若干異なります。一般的な方法は次のとおりです。

if (条件 1) // コメント

else // コメント

{

}

else if ステートメントを使用する場合は、通常、他のステートメントを処理するために else ブロックを用意するのが最善です。対処されない状況。可能であれば、else にアクションがない場合でも、else にレコード情報のコメントを入れてください。

条件付き書式設定

常に等号と不等号の左側に定数を置きます。例:

if ( 6 == $errorNum ) ...

理由の 1 つは、方程式を使用すると、文法チェッカーがエラーを報告します。 2 番目の理由は、式の最後で値を見つけるのではなく、すぐに値を見つけられることです。この形式に慣れるまで少し時間がかかりますが、非常にうまく機能します。

5.6 switch format

caseブロックが処理されると、処理のために次のcaseブロックに直接進みます。このcaseブロックの最後にコメントを追加する必要があります。

デフォルトのケースは常に存在する必要があり、到達する必要はありませんが、到達した場合はエラーがトリガーされます。

変数を作成したい場合は、すべてのコードをブロックに入れます。たとえば、

スイッチ（...）

ケース2を通してすべて：

...

}

続きと破損は、実際には隠されたgotoメソッドです。

goto と同様に、Continue と Break はコード内の魔法なので、慎重に (できるだけ使用しないで) 使用してください。この単純な魔法を使用すると、読者は何らかの理由で神だけが知っている場所に誘導されます。

Continue には主に 2 つの問題があります:

テスト条件を回避する可能性があります。

不等式を回避できます。

は次の例を見て、問題がどこで発生するかを検討します。 : プログラマーがエラーを簡単に見つけられないようにするには、「大量のコード」が必要です。

上記の例を通じて、さらにルールを導き出すことができます。「継続」と「中断」を混ぜることは、災害を引き起こす正しい方法です。

5.7.2 ?:

問題は、人々は ? と : の間に多くのコードを詰め込もうとする傾向があることです。以下に明確なリンクルールをいくつか示します:

条件を括弧で囲んでコードの残りの部分から分離します。

可能であれば、アクションは単純な関数を使用できます。

アクション、「?」、「:」は、明確に同じ行に配置できない場合は、別の行に配置します。

例:

(条件) ? funct1() : func2();

5.8 宣言ブロックの配置

宣言コードブロックアライメントが必要です。

理由：

クリア。

変数初期化のための同様のコードブロックがリストされるはずです。

&は変数名ではなく、型の近くにある必要があります。

例:

var $mDate

var& $mrDate

var& $mrName

var $mName

$mDate = 0;

$mrDate = NULL;

$mrName = 0;

$mName = NULL;

5.9 1 行に 1 つのステートメント

これらのステートメントが密接に関連している場合を除き、1 行に 1 つのステートメントのみを記述します。

5.10 短いメソッド

メソッドコードは 1 ページに制限する必要があります。

5.11 空のステートメントをすべて記録する

コードが抜けているのか、意図的に書かれていないのかが明確にわかるように、for または while の空のブロックステートメントを必ず記録します。

while ($dest++ = $src++)

; // VOID

5.12 ゼロ以外の値をテストするためにデフォルトの方法を使用しないでください

‐ ‐ ‐ ‐ ‐‐‐‐‐‐‐‐‐ ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐ ‐‐ = f())

次の方法よりも優れています:

if (f())

FAIL にも値 0 が含まれる可能性があり、これは PHP が false と見なすものです。失敗時の戻り値として 0 の代わりに -1 を使用することにした場合は、明示的なテストが役に立ちます。比較値が変わらない場合でも、明示的な比較を使用する必要があります。たとえば、if (!($bufsize % strlen($str))) は次のように記述します。 if (($bufsize % strlen($str)) == 0) テストを表す数値型 (ブール型ではない)。よくある問題は、strcmp を使用して文字方程式をテストし、その結果がデフォルト値と等しくなることがないことです。

非ゼロテストはデフォルト値に基づいているため、他の関数または式には次の制限が適用されます:

失敗を示す 0 のみを返すことができ、他の値を持つことはできません。

真の戻り値が絶対に明らかなように名前が付けられており、Checkvalid() の代わりに関数 IsValid() を呼び出します。

5.13 ブール論理型

ほとんどの関数は FALSE の場合 0 を返しますが、ゼロ以外の値は TRUE を表すため、ブール値を検出するために 1 (TRUE、YES など) の式を使用しないでください。0 を使用する必要があります ( FALSE 、 NO など) を不等式に置き換えます:

if (TRUE == func()) { ...

次のように書くべきです:

if (FALSE != func()) { ...

5.14 通常は埋め込み代入を避けます

時々、どこで埋め込まれた代入ステートメントを参照することはできますが、それらの構造は冗長性が低く可読性が高い優れた方法ではありません。 (WHILE ($ a! = ($ C = getchar ()))

{{

憲章を処理する

}}

++ および演算記号は代入ステートメントに似ています。したがって、多くの目的で、関数を使用すると副作用が発生する可能性があります。埋め込み割り当てを使用すると、実行時のパフォーマンスを向上させることができます。いずれにせよ、プログラマは、埋め込み代入ステートメントを使用する場合、速度の向上と保守性の低下との間のトレードオフを考慮する必要があります。例:

a = b + c;

d = a + r;

書かないでください:

d = (a = b + c) + r;

ただし、後者は 1 サイクルを節約できます。しかし、長期的には、プログラムの保守コストが徐々に増加し、プログラム作成者がコードのことを徐々に忘れていくため、成熟期における最適化の効果は減少します。

6. Help and Sharing

6.1 自分や他の人の努力を再利用する

共通の構造がなければ、プロジェクト間での再利用はほぼ不可能です。オブジェクトは既存のサービス要件に準拠しており、プロセスが異なればサービス要件環境も異なるため、オブジェクトの再利用が困難になります。

共通の構造を開発するには、事前に多大な設計努力が必要です。理由が何であれ、努力がうまくいかない場合は、いくつかの方法が推奨されます:

6.2 アドバイスを求める!グループにメールを送って助けを求めてください

この単純な方法はめったに使用されません。なぜなら、プログラマーの中には、他人に助けを求めると自分が劣っていると思われると感じるからです。他人がやったことを何度も繰り返すのではなく、新しくて興味深い仕事をしてください。

何かのソースコードが必要な場合、誰かが既にそれを行っている場合は、グループにメールを送って助けを求めてください。その結果は驚くべきものになるでしょう！

多くの大規模なグループでは、個人は他の人が何をしているかを知らないことがよくあります。何かやるべきことを探していて、あなたのためにコードを書いてくれる人を見つけることもできるかもしれません。人々が協力すれば、そこには常に金鉱が存在します。

6.3 教えて！何かに取り組んでいるときは、それについてみんなに伝えてください

何かを再利用できるものを作ったら、他の人に知らせてください。恥ずかしがらずに、自分のプライドを守るために自分の仕事を隠してはいけません。自分の仕事を共有する習慣が身につくと、全員がより多くの成果を得ることができます。

6.4 Small Code Base

コードの再利用に関するよくある問題は、人々が自分が取り組んだコードからライブラリを作成しないことです。再利用可能なクラスはプログラムディレクトリに隠れている可能性があり、プログラマがクラスを分割してライブラリに追加しないため、決して共有されることはありません。

その理由の一つは、人々が小さな図書館を作ることを好まないこと、そして小さな図書館に対して間違った感情を抱いていることです。この感覚を克服してください。コンピューターはライブラリの数を気にしません。

再利用できて既存のライブラリに入れられないコードがある場合は、新しいライブラリを作成します。人々が再利用について真剣に考えていれば、図書館は長い間これほど小規模なままではなくなるでしょう。

6.5 Knowledge Base

多くの企業は、どのようなコードが利用可能であるかを知りません。また、ほとんどのプログラマーは依然として自分が何をしたかを伝えていないか、どのようなコードが利用可能であるかについて常に尋ねています。これを解決するには、ナレッジベースを利用できるようにする必要があります。

理想的には、プログラマーは WEB ページにアクセスし、パッケージ化されたナレッジベースのリストを参照またはクエリして、必要なものを見つけることができます。プログラマーが自動的に保守できる知識ベースシステムを確立することは良い考えです。このナレッジベースの保守を担当する専任の管理者がいるとよいでしょう。

もう一つの方法は、コードからナレッジベースを自動生成することです。共通のクラス、メソッド、サブシステムヘッダーをマニュアルまたはナレッジベースのエントリにします。

7. コメントを書く

7.1 ストーリーを語る

コメントをシステムを説明するストーリーとして考えてください。また、コメントをマシンが解析して、固定フォーマットでマニュアルに組み込むことができます。クラスアノテーションは、メソッド名、メソッドアノテーション、メソッド実装と同様に、ストーリーの一部です。これらすべての要素が織り込まれているため、後日人々はあなたが何をしたのか、そしてなぜそれをしたのかを正確に知ることができます。

7.2 アーカイブノート

注釈をアーカイブすることだけが意味があります。そうでない場合、どのような選択をしたのか、そしてなぜそれを行ったのかを説明するメモを一か所に置いた場合、これが最も有用な情報であると考えるのは考古学者だけです。 (アーカイブ方法は別途規定します)

7.3 コメント構造

プロジェクトの各部分には特定のコメント構造があります。プログラム内のコメントについては、仕様として * @ で始まり、コメントキーワードで終わる例を示します。

7.3.1 事前定義されたキーワード

キーワードの意味

目的は、クラス、属性、またはメソッドが何をすべきか、またはそれが何を意味するかを示します。

パッケージ名クラス名

作成者作成者

変更内容変更記録（採番ルールは「No」＋日付＋「-」＋シリアル番号）

リファレンス参照

Method Name メソッド名