OpenSourcingでコードを準備してGitHubに配置するにはどうすればよいですか？

数週間で私のプロジェクトは完成し、他の人が使用できるように私のコードを準備し始めたいと思います。

私はすべてをGitHubに投稿して、人々がそれを調整して、うまくいけばそれをより良くすることができるようにします。

私が求めているのは、他の人が使用できるように私のコードが十分に文書化され、正しく記述されていることを確認するための最良の方法は何でしょうか？

私はあなたが常にすべてをコメントする必要があることを知っています、そして私はすべてのメソッドに対して@params機能を入れようとしていますが、一般的に他のヒントはありますか？

• リポジトリのルートに、ビルド方法を示すREADME.txtファイルがあることを確認してください。指示はそのファイルにある場合と、別のファイルまたはWikiページにある場合があります。
• 理想的には、1つのコマンドでコードを完全にビルドおよびテストできるようにしてください。一連の手動の手順は必要ありません。
• コードのテストがあることを確認してください。これは、コードがどのように使用されているかを他の開発者が確認するのに便利な場所を提供し、さらにコードを変更する人々にセーフティネットを提供します。コードを編集してスイートを実行し、何かを壊したかどうかを確認できることは非常に貴重です。
• 一般的なコーディング標準に従うか、使用するものを公開します。
• コードでOOを使用している場合は、少なくともすべてのパブリックメソッドと属性に十分なドキュメントがあることを確認してください
• コードが使用するライセンスが明確であることを確認してください。通常、これはLICENSE.txtファイルを含めるか、特定のライセンスに必要なメカニズムに従うことを意味します。また、ライセンスについて意識的に選択してください。あなたが知っているのはGPLだけではありません。同様に、慣れている場合は、BSDやMIT、Apacheだけを使用しないでください。1時間かけてそれらを調査し、少なくともGPLライセンスと非GPLライセンスの基本的な違いを理解してください。
• ハードコードされたユーザー名、パスワード、電子メールアドレス、IPアドレス、APIキーなどの機密情報をコードからすべて削除します（提案はHakan Deryalに感謝します）。

ソースファイル内のドキュメントは常に適切ですが、追加のドキュメントをWebサイトで公開する必要があります。その目標、それがどのように機能するか、あなたの将来の計画を説明し、貢献を簡単にしてみてください（そうでなければ...誰もあなたを助けてくれません）いくつかのチュートリアルを置きます。

ソースコードドキュメントのみを使用してプロジェクトで作業しようとすると、常にイライラします。

私が求めているのは、他の人が使用できるように私のコードが十分に文書化され、正しく記述されていることを確認するための最良の方法は何でしょうか？

オープンソースとして、すべての最も重要なコメントは、著作権とライセンス契約のコメントです。すべてのファイルの先頭にある長い長いコメントではなく、著作権を簡単に指定し、ルートディレクトリにあるlicense.txtを読者に紹介する、短くて甘いコメントを使用することをお勧めします。

私はあなたが常にすべてをコメントする必要があることを知っています、そして私はすべてのメソッドに対して@params機能を入れようとしていますが、一般的に他のヒントはありますか？

すべてにコメントしますか？いいえ。本当に必要なコードにはコメントが必要です。コメントは控えめに。コードのチャンクの潜在的なユーザーとして、クラス定義の次の2つのバージョンのうち、どちらを見たいですか？

バージョンA：

class Foo {
private:
   SomeType some_name; //!< State machine state

public:
   ...

   /**
    * Get the some_name data member.
    * @return Value of the some_name data member.
    */
   SomeType get_some_name () const { return some_name; }

   ...
};

バージョンB：

/**
 * A big long comment that describes the class. This class header comment is very
 * important, but also is the most overlooked. The class is not self-documenting.
 * Why is that class here? Your comments inside the class will say what individual parts
 * do, but not what the class as a whole does. For a class, the whole is, or should be,
 * greater than the parts. Do not forget to write this very important comment.
 */
class Foo {
private:

   /**
    * A big long comment that describes the variable. Just because the variable is
    * private doesn't mean you don't have to describe it. You might have getters and
    * setters for the variable, for example.
    */
   SomeType some_name;

public:
   ...

   // Getters and setters
   ...

   // Getter for some_name. Note that there is no setter.
   SomeType get_some_name () const { return some_name; }

   ...

};

バージョンAでは、クラス自体を除いて、すべてを文書化しました。一般に、クラスは自己文書化されていません。バージョンAにあるコメントはまったく役に立たないか、役に立たない場合よりもさらに悪いものです。それが「すべてをコメントする」態度の主な問題です。プライベートデータメンバーに関する簡潔なコメントは何も伝えません。ゲッターに関するdoxygenコメントには負の値があります。ゲッターget_some_name()は本当にコメントを必要としません。それが何をして何を返すかはコードから明らかです。セッターがないこと-ないので、それを推測する必要があります。

バージョンBでは、コメントが必要なことを文書化しました。getterにはdoxygenコメントはありませんが、setterがないことを示すコメントがあります。

コメントを重要にしてください。コメントは、コードの変更を反映するために維持されないことがよくあります。