我应该如何准备好代码以进行OpenSourcing并将其放置在GitHub上？

几周后，我的项目将结束，我想开始准备好代码供其他人使用。

我将把所有内容发布到GitHub，以便人们可以对其进行调整，并希望使其更好。

我想我要问的是，确保我的代码被充分记录并措辞正确以供他人使用的最佳方法是什么？

我知道您应该始终注释所有内容，并且我将为每种方法添加@params功能，但是一般是否还有其他提示？

• 确保在存储库的根目录中有一个README.txt文件，该文件将使人们指向如何构建它的说明。说明可以在该文件中，也可以在单独的文件或Wiki页面中。
• 理想情况下，使其成为一个完整的代码就可以用一个命令完整地构建和测试代码。不需要一堆手动步骤。
• 确保对代码进行测试。这为其他开发人员提供了一个方便的地方来查看您的代码使用方式，并且为修改您的代码的人提供了安全网。知道我可以编辑您的代码，然后运行套件以查看我是否破坏了某些东西，这是非常宝贵的。
• 遵循通用的编码标准，或发布您使用的标准。
• 如果您的代码使用OO，请确保至少所有公共方法和属性都具有足够的文档
• 确保清楚您的代码使用什么许可证。通常，这意味着包括LICENSE.txt文件，或遵循您的特定许可证要求的任何机制。另外，请仔细选择许可证。不要只使用GPL，因为这就是您所知道的。同样，如果您只熟悉BSD或MIT或Apache，请花一小时的时间对其进行研究，以便至少了解GPL和非GPL许可之间的根本区别。
• 从代码中删除所有敏感信息，例如硬编码的用户名，密码，电子邮件地址，IP地址，API密钥等。（感谢Hakan Deryal的建议）

源文件中的文档始终很好，但是您应该在网站上发布其他文档。解释其目标，工作方式，您的未来计划，尝试使贡献变得容易（否则，没有人会帮助您）并提供一些教程。

尝试仅使用源代码文档进行项目总是令人沮丧。

我想我要问的是，确保我的代码被充分记录并措辞正确以供他人使用的最佳方法是什么？

作为开源，最重要的注释是版权和许可协议注释。与其在每个文件的开头添加一个大而长的注释，不如使用简短而又可爱的，简短地指定版权并将读者指向根目录中的license.txt的注释。

我知道您应该始终注释所有内容，并且我将为每种方法添加@params功能，但是一般是否还有其他提示？

评论一切吗？否。注释确实需要注释的代码。谨慎发表评论。作为大量代码的潜在用户，您希望看到以下两个版本的类定义中的哪一个？

版本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中，我记录了需要注释的内容。吸气剂没有doxygen注释，但确实有注释，提到没有setter。

让您的评论计数，并注意通常不会维护评论以反映对代码的更改。