注释/代码内文档样式

这可能是一个愚蠢的问题，但是已经出现了一段时间，在其他任何地方都找不到合适的答案。

我有一位老师说，即使只有一个，我们也应该明确列出每个参数的描述。这导致很多重复：

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

在编写代码文档时，您有多详细？

首先，我同意您的示例中的“ Function：”行是完全多余的。根据我的经验，人们在学校教过要添加此类注释，然后继续在生产代码中添加此类注释。

好的注释不会重复代码中的内容。他们回答问题“为什么？” 而不是“什么？” 或“如何？” 它们涵盖了对输入的期望，以及代码在特定条件下的行为。它们涵盖了为什么选择算法X而不是算法Y的原因。简而言之，正是通过阅读代码，对于其他人^1而言显而易见的事情。

^{1：熟悉代码编写语言的其他人。不要写注释来教书，也不要添加注释来补充信息。}

几种语言具有API文档生成功能，例如Ruby，Java，C＃和C ++（通过命令行工具）。当您以这种方式考虑时，它使编写API文档变得更加重要。毕竟，它回答了“我该怎么办……？”这个问题。因此，我不会做任何重复的事情，例如Function: MyFunction当函数名是每个人都能看到的简单名称时。API文档生成工具足够聪明，可以帮我做到这一点。但是，以下详细信息很有用，尤其是在公共方法/功能方面：

• 摘要（它的作用以及在相关时的用法摘要）
• 参数列表以及预期内容
• 返回值（输出）将是多少
• 可以明确抛出的任何异常以及原因

当您尝试调试代码时，这些可以成为有用的参考工具。当您将鼠标悬停在函数名称上时，许多IDE也会在其工具提示中使用API​​文档。

如果是没有这些功能的语言，则注释会有所帮助，但效果却不尽相同。

如果是公共API方法，则应该提供详细的文档，尤其是有关参数和预期行为的文档。许多人认为，对于私有方法/函数YMMV可以放宽此限制。

总的来说，我更喜欢使用明智的变量名来编写干净的代码（可以很好地完成一件事和一件事的小方法/函数）。这使您的代码大部分可以自我记录。但是，我当然总是记录任何极端情况，并发使用和复杂算法。

简而言之，从现在起三个月的凌晨3点，您的自我穿戴会有些恶化。您将感谢您的出色公共文档，而不是弄清楚参数（布尔标志）的含义是什么...

这类似于大多数-Doc框架解析代码文档（JavaDoc，PHPDoc等）的方式。

从Java，由IDE自动生成：

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

这与生成内置语言功能的文档所用的格式相同-例如：http : //download.oracle.com/javase/6/docs/api/java/lang/String.html

这种格式很有用，因为它可以清楚地向任何第三方用户显示如何与您的代码进行交互。如果您的函数是仅在内部使用的私有方法，那么它可能会毫无意义-但是我猜您的老师正在努力使您成为一种良好的实践，直到您都对这种区分有所了解为止。

我经常发现唯一有点多余的地方是返回描述-通常它与我的方法描述几乎相同。

评论有两个目的：

1. 当您几个月或几年后回到代码中时，它们可以迅速提醒您代码的功能。这样，您无需重新阅读和分析代码即可刷新内存。
2. 他们会转达给其他可能正在阅读或使用您的代码的人。

当然，有许多不同的方法可以解决此问题，但是越彻底和一致，您就会越好。就像有效的编程一样，有效的注释需要花费一些时间来学习。请记住，在学校中很难看到评论的重点，因为您所做的任何事情都没有足够大到可以真正保证的程度，但是他们只是在尝试向您介绍它。通常，教你做事的方式是教授的风格，而不是任何形式的标准。开发最适合您的产品。并记住...有这么愚蠢的评论！:)示例：

a += 1; //adds 1 to the value in a

真？谢谢！大声笑

我喜欢PHP网站上的文档，因此我在内联注释中使用了类似内容，并使用了PHPDoc语法。请参见下面的示例。

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

就像@Larry Coleman所说的那样，内联注释应该告诉您为什么要编写一些代码。

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

如果为Doc生成服务，那么冗长的注释（尽管很烦人）可能是一件好事。尽管您必须将团队的目标定为始终关注评论并保持最新。

如果只是评论风格，我会对此有疑问。过多的注释会给代码带来最大的帮助。我无法计数我在代码中遇到过时的注释并因此产生误导的时间。我通常现在会忽略注释，而将重点放在阅读代码和代码测试上，以了解其作用和意图。

我宁愿有清晰简洁的未注释代码。给我一些具有描述性断言或方法的测试，我很高兴并且知道情况。