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

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