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

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
 }

让人更有意义.

摘要

对我来说,评论指南很简单:

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