Java 调用方法时是否应该进行注释？

我想知道在调用方法之前是否应该进行注释。例如：

//calling method
MethodCall();

/**
some method 
*/
public static void() {
    Statements;
}

或者javadoc对方法头进行注释是否足够好，例如：

//calling method
MethodCall();

/**
some method 
*/
public static void() {
    Statements;
}

---

我应该使用哪一种方法，还是两者都使用？

在调用方法时，注释//调用方法有什么好处？ 不管是谁在读你的代码，都会在下一行看到它

使用javadoc注释记录方法及其参数及其用途

---

注释应该解释您为什么要做某事，而不是做什么。

当您调用方法时，注释//调用方法可能会带来什么好处？ 不管是谁在读你的代码，都会在下一行看到它

使用javadoc注释记录方法及其参数及其用途

---

注释应该解释为什么要做某件事，而不是什么。

我在生产代码中经常看到这种情况，很多时候我发现自己在想为什么会有一些注释。记住好的代码注释本身

范例

从代码中可以清楚地看出，您正在调用doSomething。现在，如果在方法名称中不清楚该方法的作用或相关原因，请务必对其进行注释：

// Calling doSomething() to establish a connection to the Database.
doSomething();

但你必须问问自己，什么更有意义

添加评论 更改方法名称以使其立即可识别。 当然是后者

 public void establishDatabaseConnection() {
      // Some code
 }

这更有意义

总结

对我来说，评论指南很简单：

如果不清楚在给定上下文中调用方法的原因，请首先检查该方法的名称。如果该名称可以更改以增加清晰度，那么请更改它。如果名称尽可能清楚，并且代码很复杂，那么可以添加注释

---

我在生产代码中经常看到这种情况，很多时候我发现自己在想为什么会有一些注释。记住好的代码注释本身

范例

从代码中可以清楚地看出，您正在调用doSomething。现在，如果在方法名称中不清楚该方法的作用或相关原因，请务必对其进行注释：

// Calling doSomething() to establish a connection to the Database.
doSomething();

但你必须问问自己，什么更有意义

添加评论 更改方法名称以使其立即可识别。 当然是后者

 public void establishDatabaseConnection() {
      // Some code
 }

这更有意义

总结

对我来说，评论指南很简单：

如果不清楚在给定上下文中调用方法的原因，请首先检查该方法的名称。如果该名称可以更改以增加清晰度，那么请更改它。如果名称尽可能清楚，并且代码很复杂，那么可以添加注释

---

调用方法时请不要评论，只需调用该方法即可。除非有非常具体的理由对其进行注释，比如//TODO在修复错误xyz后删除此方法调用

这是非常无用的评论：

// add 1 to i
i = i + 1;

---

试着认识到你的代码是用代码而不是注释来编写的，所以尽可能使代码清晰。注释很容易过时。

调用方法时请不要注释，只调用方法即可。除非有非常具体的理由对其进行注释，比如//TODO在修复错误xyz后删除此方法调用

这是非常无用的评论：

// add 1 to i
i = i + 1;

---

试着认识到你的代码是用代码而不是注释来编写的，所以尽可能使代码清晰。评论很容易过时。

许多好的评论关注的是你为什么要做某事，而不是你在做什么；从代码中可以明显看出什么。在一些情况下，经常会有一些不明显的字符串，在这种情况下，注释应该用人类的术语描述正在发生的事情，通常是通过引用一个例子

---

一个重要的反例是当一个方法实现一个有点棘手的算法时。在这种情况下，最好有一个注释块，用人类的术语再次描述正在发生的事情的概要。但在这种情况下，你并不是逐行进行微评论。

许多好的评论关注的是你为什么要做某事，而不是你在做什么；从代码中可以明显看出什么。在一些情况下，经常会有一些不明显的字符串，在这种情况下，注释应该用人类的术语描述正在发生的事情，通常是通过引用一个例子

---

一个重要的反例是当一个方法实现一个有点棘手的算法时。在这种情况下，最好有一个注释块，用人类的术语再次描述正在发生的事情的概要。但在这种情况下，你不会逐行发表评论。

发表评论的许多原因之一是为了帮助他人和你理解你所做的事情以及主要原因，但没有必要写这样的评论：

// Loop through all bananas in the bunch
foreach(banana b in bunch) {
    monkey.eat(b);  //make the monkey eat one banana
}

---

发表评论的许多原因之一是为了帮助他人和你理解你所做的事情以及主要原因 可以，但不需要写这样的评论：

// Loop through all bananas in the bunch
foreach(banana b in bunch) {
    monkey.eat(b);  //make the monkey eat one banana
}

---

仅当您调用的方法具有令人困惑且神秘的参数时

---

还有其他一些情况下，调用方法的顺序非常重要，不应随意移动。这有时对文档很有用，因为有时人们会变得聪明，并尝试修复未损坏的代码。

只有在您调用的方法具有令人困惑和神秘的参数时

---

还有其他一些情况下，调用方法的顺序非常重要，不应随意移动。这有时对文档很有用，因为有时人们会变得聪明，并尝试修复未损坏的代码。

方法头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);

---

方法头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);

---

公平地说，根据您的代码，这一点差别很大

我通常喜欢文档化良好的代码，尤其是第二个示例中使用的代码——但当方法本身是自解释的时，我就不喜欢了

假设一个Point类声明一个x和y变量以及两个getter和setter，例如getX、setX。实际上，不需要评论这个类做了什么，也不需要描述它的预期用途——这是非常明显的

你应该努力使代码可读——如果你需要使用注释，它通常是代码不易阅读或理解的标志，所以在评论之前考虑更改代码。 如果您的代码在变得更加合理后仍然难以理解，那么请使用方法文档（如第二个示例）来解释方法的用途、输入和输出

只有在绝对有必要了解代码的某些重要工作方式时才使用内联注释，这些工作方式几乎不可能被猜测，并且对于其他人来说很重要，并且不适用于方法文档，或者使用它们来标记您仍然需要在方法中执行或处理的事情，比如在获取数据之前请记住检查用户是否登录。这样，当您浏览代码时，您可以看到您的注释并记住您仍然需要做什么

就我个人而言，我最初使用内联注释来描述一个没有代码的方法，例如

public double divideNumbers(double top, double bottom){
    //Check bottom is different from zero and throw exception if zero
    //Divide top with bottom
    //Return result
}

---

通过这种方式，我可以一个接一个地接受注释，实现它，然后继续下一条注释。

公平地说，根据代码的不同，这会有很大的不同

我通常喜欢文档化良好的代码，尤其是第二个示例中使用的代码——但当方法本身是自解释的时，我就不喜欢了

假设一个Point类声明一个x和y变量以及两个getter和setter，例如getX、setX。实际上，不需要评论这个类做了什么，也不需要描述它的预期用途——这是非常明显的

你应该努力使代码可读——如果你需要使用注释，它通常是代码不易阅读或理解的标志，所以在评论之前考虑更改代码。 如果您的代码在变得更加合理后仍然难以理解，那么请使用方法文档（如第二个示例）来解释方法的用途、输入和输出

只有在绝对有必要了解代码的某些重要工作方式时才使用内联注释，这些工作方式几乎不可能被猜测，并且对于其他人来说很重要，并且不适用于方法文档，或者使用它们来标记您仍然需要在方法中执行或处理的事情，比如在获取数据之前请记住检查用户是否登录。这样，当您浏览代码时，您可以看到您的注释并记住您仍然需要做什么

就我个人而言，我最初使用内联注释来描述一个没有代码的方法，例如

public double divideNumbers(double top, double bottom){
    //Check bottom is different from zero and throw exception if zero
    //Divide top with bottom
    //Return result
}

---

这样我可以一个接一个地接受注释，实现它，然后继续下一个注释。

不，这只会增加代码混乱。重复的原因是什么？如果该方法被重命名怎么办？你必须更新评论，w 这是双重工作

//calling method
MethodCall();

---

不，这只会增加代码混乱。重复的原因是什么？如果该方法被重命名怎么办？您必须更新注释，这是双重工作

//calling method
MethodCall();

---

//调用方法和方法调用；基本相同。你不应该两者都需要。在我看来，你不必做调用方法…-事情。当您解释代码的某些行/部分时，您应该给出注释，而不是指出明显的事情。javadoc的方法头总是一件好事//调用method和MethodCall；基本相同。你不应该两者都需要。在我看来，你不必做调用方法…-事情。当您解释代码的某些行/部分时，您应该给出注释，而不是指出明显的事情。javadoc的方法头总是一件好事。谢谢你的小讲座，因为我真的需要它，因为我看到了评论这么多lol。谢谢！谢谢你的小讲座，因为我真的需要它，因为我看到了评论这么多lol。谢谢！