我想知道在调用方法之前是否应该评论。例如：
//calling method
MethodCall();
或者使用 javadoc 对方法头进行注释是否足够好，例如：
/**
some method
*/
public static void() {
Statements;
}
我应该使用哪一个，或者我应该同时使用哪一个？
【问题讨论】：
//calling method 和MethodCall(); 基本相同。你不应该两者都需要。
不，这只会增加代码混乱。重复的原因是什么？如果方法被重命名怎么办？您必须更新 cmets，这是一项双重工作。
//calling method
MethodCall();
【讨论】：
公平地说，这取决于您的代码。
我通常喜欢记录良好的代码，尤其是在您的第二个示例中使用的代码 - 但当方法本身是不言自明的时候就不喜欢了。
想象一个 Point 类声明一个 x 和 y 变量以及 2 个 getter 和 setter（例如 getX、setX）。没有必要评论这个类的作用或描述它的用途——这很明显。
您应该努力使代码具有可读性 - 如果您需要使用 cmets，这通常表明您的代码不易阅读或理解，因此请考虑在注释之前更改您的代码。
如果您的代码在变得更合理后仍然难以理解，请使用方法文档（如您的第二个示例）来解释方法的目的、输入和输出。
仅在绝对有必要了解您的代码的某些重要工作方式（几乎不可能猜到）、对其他人理解很重要且不适合方法文档时才使用 INLINE cmets - 或使用它们来标记您仍然需要在您的方法中执行或处理的事情，例如“记住在获取数据之前检查用户是否已登录”。这样，当您查看您的代码时，您可以看到您的 cmets 并记住您还需要做什么。
我个人使用内联 cmets 来描述最初没有代码的方法，例如
public double divideNumbers(double top, double bottom){
//Check bottom is different from zero and throw exception if zero
//Divide top with bottom
//Return result
}
这样我可以一个一个的拿评论，实现它，然后继续下一条评论。
【讨论】：
方法头 javadoc 注释总是一个好主意。所以对于大多数函数调用来说，这就足够了，但有时你也会想在调用它的地方添加注释。当您使用一些默认（魔术！）数字调用方法时，是添加评论的好地方，解释您为什么使用您使用的魔术数字。
例如，给定以下函数
/**This function takes the following arguments.... */
public int foo(int a, int b){//does stuff}
如果我有两个输入（第一个和第二个），我不会费心评论这个电话：
foo(first, second);
但如果我只有第一个，并且想使用默认的 42，我会评论：
//the default is 42, because it is the answer to life, the universe, and everything.
foo(first, 42);
【讨论】：
仅当您调用的方法具有令人困惑和神秘的参数时。
在其他情况下，您调用方法的顺序非常重要，不应该左右移动。这有时对记录很有用，因为有时人们会变得聪明并尝试修复没有损坏的代码。
【讨论】：
评论的众多原因之一是帮助他人（和您）了解您所做的事情和主要原因，但没有必要写这样的评论：
// Loop through all bananas in the bunch
foreach(banana b in bunch) {
monkey.eat(b); //make the monkey eat one banana
}
【讨论】：
许多优秀的 cmets 关注为什么你在做某事，而不是你在做什么；从代码中应该很明显。在某些情况下（通常是字符串修改），其中的内容并不明显，在这种情况下，注释应该用人类的术语来描述正在发生的事情，通常是通过引用一个例子。
一个重要的反例是当一个方法实现一个有点棘手的算法时。在这种情况下，最好有一个注释块来描述（同样，用人类的术语）正在发生的事情的轮廓。但在这种情况下，您不是逐行“微评论”。
【讨论】：
调用方法时请不要评论，调用方法即可。除非有一个非常具体的理由来评论它，比如“// TODO 在 bug xyz 修复后删除这个方法调用”
这是非常无用的评论：
// add 1 to i
i = i + 1;
尝试意识到您是在代码中而不是在 cmets 中编写代码，因此请让您的代码尽可能清晰。评论很容易过时/过时。
【讨论】：
我在生产代码中看到了很多这样的情况，而且很多时候我发现自己想知道为什么有些 cmets 甚至在那里。记住好代码本身。
示例
public void doSomething() {
// Some code
}
public static void main(String[] args)
{
// Calling doSomething()
doSomething();
}
从代码中可以清楚地看出，您正在调用doSomething。现在，如果在方法名称中不清楚，该方法的作用（或为什么相关），那么一定要评论它：
// Calling doSomething() to establish a connection to the Database.
doSomething();
但是你必须问自己，什么更有意义？
而且肯定是后者。
public void establishDatabaseConnection() {
// Some code
}
更有意义。
总结
对我来说，cmets 的指南很简单：
如果不是明确说明，为什么要在给定上下文中调用方法，则首先检查该方法的名称。如果可以更改该名称以增加清晰度，请更改它。如果名称尽可能清晰，而您的代码简单复杂，则可以添加注释。
【讨论】：
当您调用方法时，评论//calling method 可能有什么好处？
任何正在阅读您的代码的人都会在下一行看到它。
使用 javadoc cmets 记录方法及其参数的用途。
评论应该解释为什么你在做某事，而不是什么。
【讨论】：