c++ - リリース用のパブリックヘッダーを準備する

Question

顧客に配布するパブリックヘッダーファイルをクリーンアップするために、どのようなルーチンがあるかを知りたいです。

ご意見をお聞きしたいのは、次のような点です。

外部消費向けではないコメント。一般的に、私はドキュメントをコードの近くに置いておくのが好きで、このようなコメントは共有するのに良い考えではないかもしれません:

/**
 * @todo Should we change the signature of this function to
 * make it obvious that xxx is really yyy?
 */

多分：

/**
 * @todo Add support for feature X
 */

一貫性のないタブスタイル:

void functionA(int a, 
     int b,
     int c,
     int d);

void functionB(int a,
               int b,
               int c);

リリースに向けてヘッダーやコード全般を準備するためのツールはありますか?

score 14 · Accepted Answer

常に、長期間にわたって複数の開発者が関与するプロジェクトと、その後のそのソースコードのリリースでは、SCAN FOR OBSCENITIES（および、「上司が私にこれを行わせた」など、言うべきではないその他のこと）を行う必要があります。「このコードはひどい」など）。また、コメントのスペルチェックは、単語のスペルを間違えると信頼性が低下するため、役立つ場合があります。

score 11 · Accepted Answer

11

ヘッダーがコンパイラの警告を生成しないことを確認してください。

于 2009-06-05T11:59:40.687 に答える

score 3 · Accepted Answer

常に誰か (できれば複数) にヘッダーを調べてもらい、プロらしくないように見えるものを探してもらいます。最初に、コードフォーマッタやその他の自動ツールを使用できます。

コメントについては、専門外または暫定的なものを探してもらいます。スペルミスを修正します。それらが正確であることを確認してください。それらをフォーマットする標準的な方法を用意し、それに固執してください。

すべての識別子名を確認します。スタイルガイドに準拠し、専門的な名前を付ける必要があります。

必要なコメントがすべて含まれていることを確認してください。これには、上部に著作権と連絡先情報が含まれます。クラスなどを文書化する標準的な方法を考え出し、それを実施します。

基本的に、私の見解では、ヘッダーは、創造性やユーモアのセンスがなく、完全に一貫性のあるドローンによって作成されたように見える必要があります (CPA のステレオタイプのようなものです)。(これは、顧客がオフィスを訪れている間、開発者にスーツを着るように頼むようなものです。顧客は、開発者が実際にどのようなものであるかを知らなければ、より幸せになります。)

score 2 · Accepted Answer

開発者が最初にコードを作成するときに顧客が参照するドキュメントのコーディング標準/形式があれば、一般的には良いでしょう。これにより、現在のように、リリース前にコードをクリーンアップするのに時間を費やす必要がなくなります。

また、Visual Studio および他のいくつかの IDE には、スタイルを設定できる「自動フォーマット」オプションがあり、それがコード (タブ、スペースなど) に適用されます。それがあなたがここで求めていることのほとんどだと思います。

score 2 · Accepted Answer

私はこの件についてあまり詳しくありませんが、オープンソースプロジェクトの場合、ヘッダーの上部にライセンスと著作権のステートメントが記載されていることがよくあります。これにより、いくつかの法的な問題を回避できます。

score 2 · Accepted Answer

不適切なコメントを削除するのと同じくらい重要なのは、必要なコメントを追加することです。追加する必要があるかもしれないもの:

著作権/利用規約ヘッダー
サポートの連絡先情報
ドキュメントがオンラインで利用可能になっている場合は、ドキュメントへのリンク
パブリックインターフェイスのドキュメント (戻り値、パラメーター、事前および事後条件など)
公開されているが本番環境での使用を意図していない関数/メソッドに関する警告

score 2 · Accepted Answer

私の経験では、内部で使用されるヘッダーを定期的かつ自動的にクリーンアップして公開するのは難しい作業であり、間違いなくエラーが発生しやすくなっています。最終的には、一貫性のない形式や不適切なコメントが忍び寄ることは避けられません。

多くの場合、すべてを小さくてきれいなインターフェースにラップする方がよいでしょう。そのヘッダーは常にきれいに維持され、可能な限りコメントが付けられます。たとえば、そのファイルへの変更は、特に慎重なレビュープロセスを受ける必要があります。

score 1 · Accepted Answer

こんばんは

C++ では、Handle-Body のイディオムを使用して、パブリックインターフェイスから実装を可能な限り分離するのが好きです。

また、ボイラープレート (著作権表示など) が一貫していて最新であることを確認する必要があります。たとえば、今日リリースされたコードの著作権は 2008 年に期限切れになりません。

命名規則、書式設定、レイアウト、およびクラス設計について、すべてのパブリックヘッダーファイルで一貫性を持たせてください。そうしないと、顧客に専門的でない印象を与えてしまいます。

ヘッダーファイルに "using" 宣言がないことを確認してください。dec の「使用」の誤用は、不注意による副作用で事態を深刻に台無しにする可能性があります。

前述のように、ヘッダーが警告を生成しないことを確認してください。

ついに。ヘッダーファイルに対応する優れた API ドキュメントがあることを確認してください。

よく知られている郵便番号検索製品を提供する会社のようになってはいけません。C API の最初のバージョンには、Windows GUI バージョンに大きく基づいた最小限のドキュメントが付属していました。ヘッダーファイルは単純に、パラメーターが型のみで名前のない関数で構成されていました。そして、コメントは一切ありません。

関数が実際に何をしたかを理解する唯一の方法は、提供された単純なルックアップサンプルプログラムをリバースエンジニアリングし、それをリバースエンジニアリングすることでした。

それでも、BBC の「Children in Need」で年間数万ポンドを節約できたのは、募金パックに提供された住所が以前よりも正確である可能性が高かったからです。

c++ - リリース用のパブリック ヘッダーを準備する

8 に答える 8

Related

Reference

c++ - リリース用のパブリックヘッダーを準備する