注释代码 [英] Commenting code

问题描述

可能重复：

您是否对您的代码进行评论？

我问，因为我和朋友正在创办一家公司，可能需要有一些商定的标准

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屋！