Question

我想知道在调用方法之前是否应该发表评论。例如：

//calling method
MethodCall();

或者对于方法标题的javadoc注释是否足够好，例如：

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

我应该使用哪一个，还是应该同时使用它们？

Answer 1

当您调用方法时，您可以通过评论//calling method获得什么好处？无论是谁在阅读你的代码，无论如何都会在下一行看到它。

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

评论应该解释为什么你正在做某事，而不是是什么。

Answer 2

我在生产代码中看到了这么多，而且很多时候我发现自己想知道为什么有些评论甚至存在。请记住好的代码评论本身。

示例

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
 }

更有意义。

摘要

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

如果它不是明确清除，为什么要在给定的上下文中调用方法，那么首先检查该方法的名称。如果可以更改该名称以增加清晰度，则更改它。如果名称尽可能清晰，并且您的代码很复杂，那么您可以添加注释。

Answer 3

评论的众多原因之一是帮助其他人（和你）理解你做什么的主要原因，但是没有必要写下这样的评论：

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

Answer 4

调用方法时请不要注释，只需调用方法即可。除非有一个非常具体的理由来评论它像“//在修复bug xyz之后删除此方法调用”

这是非常无用的评论：

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

尝试意识到您使用代码而不是注释进行编码，因此请尽可能使代码清晰。评论很容易变老/过时。

Answer 5

许多好的评论都集中在为什么你正在做某事，而不是你正在做的事情;从代码中可以明显看出来的东西。在某些情况下（通常使用字符串调整），不明显的是，在这种情况下，评论应该通过引用一个例子来描述人类发生的事情。

一个重要的反例是当一个方法实现一个有点棘手的算法时。在这种情况下，让评论块描述（再次，用人类术语）描述正在发生的事情的轮廓是很好的。但在这种情况下，你不是逐行“微观评论”。

Answer 6

只有当您调用的方法具有令人困惑且含糊不清的参数时。

还有其他情况，您调用方法的顺序非常重要，不应该四处移动。这有时对文档有用，因为有时人们会变得聪明并尝试修复未破坏的代码。

Answer 7

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

Answer 8

公平地说，这取决于您的代码。

我通常喜欢记录良好的代码，特别是第二个例子中使用的代码 - 但是当方法本身是自我解释时不是。

想象一个Point类声明一个x和y变量以及两个getter和setter（例如getX，setX）。没有必要评论这个类的功能或描述它的用途 - 这很明显。

您应该努力使代码可读 - 如果您需要使用注释，通常表明您的代码不易阅读或理解，因此请在评论之前考虑更改代码。

如果您的代码在使其更合理之后仍然难以理解，那么请使用类似于您的第二个示例的方法文档来解释方法的目的，其输入和输出。

如果绝对有必要了解您的代码中几乎无法猜测的一些重要工作，并且对于其他人理解并且不适合方法文档很重要 - 或者使用它们来标记，则仅使用INLINE注释您仍然需要在您的方法中执行或处理的事项，例如“记住在获取数据之前检查用户是否已登录”。这样，当您查看代码时，您可以看到您的评论并记住您仍需要做什么。

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

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

通过这种方式，我可以逐个发表评论，实施，然后继续下一个评论。

Answer 9

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

//calling method
MethodCall();

在调用方法时我应该评论吗？

9 个答案: