リリースのパブリックヘッダーを準備する

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); 

ヘッダーやコードを一般的にリリースするためのツールはありますか？

Answer 1

長時間にわたり複数の開発者が関与しているプロジェクトであれば、そのソースコードSCAN FOR OBSCENITIES（およびあなたが言ってはいけないこと以外は、「私の上司が私を作ったこれを行う "、"このコードはひどいです "など）。また、コメントのスペルチェックは、あなたの信頼性から誤って単語を綴じる人々のために役立ちます。

Answer 2

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

Answer 3

コードを作成するときに開発者自身が従う文書が表示されるので、リリース前にコードをクリーンアップしていない文書。

また、Visual Studioや他のいくつかのIDEには、スタイルを設定できる「自動書式設定」オプションがあり、コード（タブ、スペース、そのようなもの）に適用されます。私はそれが主にあなたがここで求めているものだと思います。

Answer 4

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

Answer 5

やあ、Cで

は++私は、パブリックインターフェイスから可能な限り実装を分離するためにHandle-Body idiomを使用したいです。

また、ボイラープレート（例：一貫性があり、最新のものです（例：今日リリースされたコードの著作権は2008年に失効しません。

命名規則、書式設定、レイアウト、およびクラス設計のために、すべてのパブリックヘッダーファイルで一貫性を保つ必要があります。それ以外の場合は、顧客にプロフェッショナルな印象を与えません。

ヘッダファイルに "using"宣言がないことを確認してください。 decを使用することの誤用は、重大な副作用を引き起こす可能性があります。

前述したように、ヘッダがのいずれの警告も生成しないようにしてください。警告。

最後に、あなたのヘッダーファイルに行くための良いAPIドキュメントがあることを確認してください。

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

機能が実際に行ったことを理解するには、提供されている単純なルックアップのサンプルプログラムをリバースエンジニアリングしてリバースエンジニアリングするしかありませんでした。

しかし、資金調達パックに提供された住所がこれまでよりも正確になる可能性があるので、私はBBCの子供の必要性を年に数万ポンド節約できました。

Answer 6

私の経験では、内部的に使用されるヘッダーを一般消費者のために定期的かつ自動的にクリーンアップするのは難しい作業ですが、間違いなくエラーが発生します。結局のところ、一貫性のない形式や不適切なコメントは必然的に消え去ります。

多くの場合、ヘッダーが常にきれいでコメントとして管理されている、小さくて清潔なインターフェイスにすべてをラッピングする方がよいでしょう。そのファイルへの変更は、例えば特に慎重なレビュープロセスを経なければならない。

Answer 7

重要なコメントを削除することは、必要なコメントを追加することと同じくらい重要です。

• 著作権/用語-の使用ヘッダー
• 連絡先情報をサポートするためにドキュメントへ
• リンクを、それがパブリックインターフェイスの
• オンラインで利用可能ドキュメント（リターン行われている場合：あなたが追加する必要があります物事値、パラメータ、前後の条件等）が露出が、生産使用のために意図されていない機能に
• 警告/方法

Answer 8

プロフェッショナルに見えるものを探すために、常に誰か（できれば複数）がヘッダーを通過するようにしてください。コードフォーマッタやその他の自動ツールを先に使用することができます。

コメントのために、プロフェッショナルでないものや暫定的なものを探すようにしてください。スペルミスを修正してください。それらが正確であることを確認してください。それらをフォーマットし、それに固執する標準的な方法を持ってください。

すべての識別子の名前を確認してください。彼らはスタイルガイドに従って、専門的に名前を付ける必要があります。

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

基本的には、私の視点から見ると、あなたのヘッダーは創造性やユーモアのセンスのないドローンによって制作されたように見えますが、完全に一貫しています（CPAステレオタイプのようなものです）。あなたの開発者が本当に好きなものを見ないと顧客はもっと幸せになれます。