注释码
Possible Duplicate: Do you comment your code?
什么是代码文档的不同标准和惯例，哪些最适合我们？
我之所以这样问是因为我和朋友正在创办一家公司，可能需要达成一些共识，以便对事物进行评论，以便我们可以更轻松地阅读彼此的代码。
解决方案
回答
我将从注释所有类(文件名，动态版本/最后作者/修订历史的版本控制标签，类目的)和方法(使用，参数，返回值)的注释开始，并确保所有类和方法都记录在符合这些标准。
回答
当然，这取决于语言，但是通常每种方法的注释都是标准的，这些方法描述其功能，输入所需的内容和输出所需的内容。我们也可以根据需要添加作者姓名和日期，但是很可能会在版本控制应用程序中显示出来。
至于其他注释，请谨慎使用，并确保在记录特定代码行时描述原因而不是方法。
回答
我发布了有关此内容的信息，如果我们命名解释它们的含义或者作用的变量和函数，它将使生活更加轻松。因此，应使用注释来解释为什么以现有方式对其进行编码。
回答
看一下"官员"一词的建议。我会遵循这一点，因为将来与我们一起工作的人都有可能听说过甚至使用它。我将尽量避免"发明"我们自己的标准。
回答
首先，标准应该是代码不需要注释-它应该是自我记录的。换句话说，评论应解释我们为什么以特定方式解决问题。
我个人讨厌CS101评论：
int Count = 0; // initialize Count to zero
回答
值得记住的是，评论总是错误的。当我们执行诸如编写列出所有参数和返回值之类的大函数标头注释之类的操作时，这一点尤其重要。我们可以保持很长一段时间，但是最终随着代码库的增长，注释块将与实际代码不同步。我们将更改参数的名称，或者添加一个新的参数，而忘记更新注释。然后，该评论是错误的，因此是无用的。
正如其他人提到的那样，评论应该解释我们为什么做某事，而不是我们在做什么。通过阅读代码可以回答什么。
回答
这是我的工作。首先，我用Doxygen在标头中注释类和方法，因为我在家中使用Java而在工作中使用C ++，这很有用，尽管如果我们使用某种形式的.net，则可能会使用Microsoft对其进行哈希处理。
对于内联注释，我更喜欢对代码块进行注释：这是下一个代码块(或者应该这样做)的作用。不要注释任何一行，因为这没有意义，而且往往没有帮助。例外情况是在语言实现中存在错误时执行了解决方法，这在使用VC6时很有用。
回答
正如其他人所说的那样，代码应该是自我注释的，因此名称，事件和对象都应尽可能容易地反映和阅读其所要实现的目标。
除此以外，当需要进一步解释某些内容时，还应使用其他注释，以说明为什么会失败(此公式和值由于x而被选择，请参见bug等)。
(如果这是.NET，并且我们还希望提供Windows帮助文件，则可以查看Ghostdoc及其提供的注释，以及Sandcastle [Sandcastle [Windows帮助文件构建器，它将获取代码xml注释并从API生成帮助文件]。 )
但是通常的经验法则是，在99％的时间里，代码应具有可读性，逻辑性，并分解为有意义的方法，这样我们除了代码之外就不需要任何东西，然后仅需填写注释真正需要进一步解释的空白。
回答
我要求提供函数标题注释，但仅在绝对需要描述内部函数注释时才要求它们，例如，描述API错误或者其他一些必不可少但不明显的技术的变通方法。
标头评论应：
- 描述该功能的目的。
- 描述任何参数的目的。
- 描述返回值的目的。
其他评论，注释或者用法示例也可以包括在内，但不是必需的。
是的，评论可能而且确实变得不准确。没有逃避的机会，但是也没有理由把婴儿和洗澡水一起扔出去。正确时，注释可以为我们节省大量时间，以试图超越代码的意图。相信这些评论，但是当我们遇到错误时，请进行验证并花一点时间来纠正错误。
回答
首先，注释应该清晰，简洁，与其注释的代码相关，并提供通过实际阅读代码无法轻易获得的价值。例如，记录为什么选择特定的哈希算法而不是可用于密码哈希功能的其他算法。
如果使用的是基于.NET的语言之一，则应同时对公共成员和私有成员使用XML注释，因为Visual Studio将使用此信息显示类的智能感知。我们还可以使用这些注释通过SandCastle之类的工具自动生成API文档。这的确意味着信息需要保持最新，但这只占所花费时间的很小一部分。如果我们不使用一种基于.NET的语言，则可以使用其他工具(例如Doxygen或者Javadoc)来提供注释和类似于XML注释的功能。
我们还应该在记录内容和记录方式上保持一致。如果放置文件头，请在每个文件中放置相同的头(仅更改必要的内容，例如文件名)。
回答
我通常只使用这些指针。
我使用"标头注释"来记录函数，类等。通常，注释比注释更多。我使用Cand Visual Studio，为此使用XML注释时，我们会获得一些不错的功能。
注释应说明我们为什么做某事，而不是我们所做的。代码应该足够清楚以表明这一点，如果没有，请更改代码。重复执行代码的注释与重复代码一样糟糕。更新代码时，有时会忘记注释，造成的弊大于利。
评论应保持在最低限度。注释是本地的，需要维护。如果可以的话，请不要使用它们
回答
在我看来，自我注释代码有点像个小玩意儿。没有这样的事情。当然，代码需要简洁明了，但这与注释无关。那是关于代码质量。
另一方面，注释应说明代码解决的问题以及原因。通过阅读代码本身可以理解代码的工作方式。注释应该是关于为什么有代码的原因。
回答
简而言之，请评论原因，而不是方法。我认识到，鉴于其他答案，这是多余的，但还不够充分。
编写代码和注释，以便我们在6个月后回来并修复存在的错误时易于阅读。另外，如果编写的代码清晰易懂，则请注意不要过度注释。这会使代码难以阅读。换句话说，对必须维护代码的人好。
我强烈建议我们阅读"代码完成"以及其中的注释部分。
回答
当我上大学时，我从另一位开发人员那里获得了一个评论约定，多年来为我提供了很好的服务。它的想法是使我们能够快速，轻松地扫描文件，以查找某些内容或者获得其结构的概述。我为每个公共或者受保护的方法或者属性添加以下注释结构：
/* ====== MethodName ====== */ /// <summary> /// XML comments go here /// </summary> void MethodName()
到目前为止，在我所看到的所有约定中，至少在我看来，这似乎是使每种方法脱颖而出的最清晰方法，并且它使得最快速地扫描源代码文件变得最容易。话虽如此，由于尖括号税的视觉混乱，我讨厌复仇的XML注释，我希望Microsoft能够在Javadoc或者PHPdoc的基础上解决更多问题：
/* ====== methodName ====== */ /** * Doc comments go here * * @param A parameter * @returns A number */ int methodName(String param)
除此之外，我尝试使代码尽可能地自我记录。理想情况下，每种方法都应执行一个特定任务(当然可以分解为子任务)，其名称应描述其功能。
回答
我确实相信这篇文章是相关的。 http://www.codinghorror.com/blog/archives/001150.html
回答
为了使人们在以后需要略读代码以找出中断的地方或者可能需要更新的内容，注释该怎么办？这是我从网上找到的一个例子。
http://www.example-code.com/csharp/ssl_async_client.asp
我想如果我们要调试此代码，则此示例非常好。也许需要更多"为什么我要这样做"，但还不错。
我发现我正在做的大部分工作是调试和维护那些已久未使用或者不可用的人编写的代码库中完全不同的应用程序。要找到一个错误，否则我们可能必须阅读每一行代码，看来效率低下，不是吗？
我希望看到更多具有良好评论示例的示例。
