评论代码 [英] Commenting code

问题描述

可能重复：

你的评论代码？

有什么不同代码文件的标准和做法，最适合您？

What are the different standards and practices of code documentation and which have worked best for you?

我问，因为我和朋友正在创办一家公司，可能需要达成一致的标准评论的东西，使我们可以更容易地阅读对方的代码。

I ask because myself and friend are starting a company and will probably need to have some agreed upon standard for commenting things so that we can read each other's code more easily.

推荐答案

首先，评论应该是清晰，简洁，相关他们正在评论的代码，并提供实际阅读代码不容易获得的价值。例如，记录为什么选择一个特定的散列算法可供密码散列函数使用。

First and foremost, comments should be clear, concise, relevant to the code they are commenting, and provide value that isn't readily available by actually reading the code. For example, documenting why a particular hashing algorithm was chosen over the others available for a password hash function.

如果您使用的是基于.NET的语言之一，那么应该对公共和私有成员使用XML注释，因为Visual Studio将使用此信息为您的类显示智能感知。您也可以使用这些注释，使用SandCastle等工具自动生成API文档。这意味着信息需要保持最新，但这应该是一个非常很小的时间花费的时间。如果您不使用基于.NET的语言，还有其他工具（如Doxygen或Javadoc）提供与XML注释类似的注释和功能。

If you are using one of the .NET based languages, you should use XML comments for both public and private members as Visual Studio will use this information to display intellisense for your classes. You can also use these comments to automatically generate API documentation using tools like SandCastle. This does mean the information needs to be kept up to date, but that should be a very small percentage of time spent. If you aren't using one the .NET based languages, there are other tools (like Doxygen or Javadoc) that provide comments and functionality similar to XML comments.

您应该您的文档和文档的方式也一致。如果你放置一个文件头，将相同的标题放在每个文件中（只改变必要的东西，如文件名）。

You should also be consistent in what you document and how you document. If you put a file header, put the same header in each file (changing only what is necessary, such as the file name).

这篇关于评论代码的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！