10

私は常にコードのドキュメント化に取り組んできましたが、AJAX + PHP となると、必ずしも簡単ではありません。コードは本当に散らばっています。ロジック、データ、プレゼンテーション (名前を付けます) は、サーバー側とクライアント側のコードの間で分割され、混合されます。作業の一部を実行するデータベース側のコード (ストアド プロシージャ、ビューなど) が存在する場合もあります。

これは、そのようなコードを文書化するための効率的な方法を考え出すことに挑戦します。私は通常、.php ファイル内の .js ファイルのリストと、.js ファイル内の .php ファイルのリストを提供します。また、インライン コメントと関数の説明も行います。ここでは、どの関数がどのファイルで使用され、どのような出力が期待されるかをリストします。データベース プロシージャについても同様のタスクを実行します。多分もっと良い方法がありますか？

アイデアや経験はありますか？

注: この質問は、Javascript+PHP だけでなく、あらゆるクライアント + サーバー側アプリケーションに適用されます。

4

4 に答える 4

4

あなたの方法はかなり良いと思います。唯一のことは、jsファイル内のすべてが他の人に読めることです。したがって、使用されているPHPファイルを文書化すると、セキュリティホールが発生する可能性があります。また、大したことではありませんが、トラフィックの多いサイトでは、500バイトのコメントをダウンロードすると合計される可能性があります。

これらは両方とも大きくはありませんが、私が以前に持っていた考えだけです。

于 2008-10-05T06:39:17.553 に答える
3

階層的なアプローチを取るのが最善だと思います。

関数やクラス レベルのような api レベルのドキュメントについては、コードにインライン ドキュメントを記述し、多くのドキュメント ツール ( JSDoc、phpDocumentor、OraDocletなど) を使用して、インライン ドキュメントから HTML ドキュメントを生成します。ドキュメント ツールをソース管理ツールと統合して、API ドキュメントから特定のコード行にジャンプできる場合はボーナス ポイントです。

ドキュメント ツールを配置したら、新しいビルドごとにビルド プロセスの一部としてドキュメントの生成を開始し (ビルド プロセスがありますよね?)、ドキュメントを標準の Web の場所にプッシュします。

これらの API ドキュメントがオンラインになったら、ブラウザ -> ウェブ -> データベースの相互作用、ユーザー ストーリー、スキーマ図などの高レベルのドキュメント用の wiki を作成できます。必要に応じて API ドキュメントとソース管理にリンクします。

于 2008-10-05T15:15:17.747 に答える
1

PHP を介して JavaScript (および CSS) を提供します。ソース ファイルをまとめて簡単に相互参照できるようにし、ヘッダーを慎重に使用することでキャッシングを簡単に処理できます。これを行うと、適切にフォーマットされたコメントの多いソース バージョンを作成して、ブラウザーに送信する前に圧縮または難読化することもできます。

function OutputJs($Content) {
    ob_start();
    echo $Content;
    $expires = DAY_IN_S;
    header("Content-type: x-javascript");
    header('Content-Length: ' . ob_get_length());
    header('Cache-Control: max-age='.$expires.', must-revalidate');
    header('Pragma: public');
    header('Expires: '. gmdate('D, d M Y H:i:s', time()+$expires).'GMT');
    ob_end_flush(); 
}
于 2008-10-10T15:34:41.890 に答える
0

多くの JavaScript を使用するプロジェクトの場合、JavaScript ミニマイザーを備えたビルド システム (メイクファイル) を使用します。jsmin の作成者が指摘しているように、コメントを削除すると、「クリーンで読み書きのできる自己ドキュメントのダウンロード コストがなくなるため、より表現力豊かなプログラミング スタイルが促進されます」。

おまけに、jsmin は CSS からコメントを削除するので、そこにも自由にコメントを書き始めることができます。(明確な JavaScript を作成するには、css クラスを使用することが重要であることがわかりました。)

PHP を使用して動的にコードを取り除き、javascript ファイルを整理するのは興味深いアイデアです。Web アプリの重要な最適化は、HTTP 要求を減らすことであることに注意してください。そのため、多くの場合、小さな JavaScript ファイルを結合することが賢明です。(最小化された js ファイルを単一のファイルに連結するだけでうまくいくことがわかりました。)

于 2008-11-12T15:12:04.700 に答える