我應該在調用方法時發表評論嗎？

Question

我想知道在調用方法之前是否應該發表評論。例如：

//calling method 
MethodCall(); 

或者是與例如方法頭的Javadoc註釋不夠好：

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

哪一個，我應該使用或我應該同時使用？

Answer 1

一個很多原因的註釋是幫助otherss（和你），以瞭解和主要你爲什麼你做什麼，但沒有必要寫評論像這樣：

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

Answer 2

當您調用方法時，您可能從評論//calling method中獲得什麼好處？ 無論誰在閱讀你的代碼，都會在下一行看到它。

使用javadoc註釋來記錄方法及其參數的用途。

註釋應該解釋爲什麼你正在做的事情，沒有什麼。

Answer 3

我在生產代碼中看到了這一點，很多時候我發現自己想知道爲什麼有些評論甚至在那裏。記住好代碼自己評論。

例

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 4

請不要在調用方法時進行註釋，只需調用方法即可。除非有非常特殊的原因發表評論它喜歡「// TODO刪除此方法調用之後的錯誤xyz是解決」

這是非常無用的評論：

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

努力實現你的代碼代碼而不是在註釋中，所以儘可能使你的代碼儘可能清晰。評論很容易變老/過時。

Answer 5

很多好評都集中在爲什麼你在做什麼，而不是你在做什麼;代碼中應該顯而易見的是什麼。有些情況下（通常是用字符串消除）不明顯的地方，在這種情況下，評論應該通過引用一個例子來描述人類發生的事情。

一個重要的反例是當一個方法實現了一個有點棘手的算法。在這種情況下，最好有一個評論塊（用人的話來說）描述正在發生的事情。但在這種情況下，你並不是一條一條地「微觀評論」。

Answer 6

只有如果你調用的方法有混淆和神祕的參數。

還有其他的情況下，你調用方法的順序是非常重要的，不應該四處走動。這對於文檔有時很有用，因爲有時候人們會變得聰明，並嘗試修復未被破壞的代碼。

Answer 7

方法頭javadoc評論總是一個好主意。因此，對於大多數函數調用來說，這已經足夠了，但有時您也會在調用它的地方添加註釋。當你用一些默認（magic！）號碼調用某個方法時，它是添加評論的好地方，解釋你爲什麼使用了你使用的魔術數字。

例如，假設下面的函數

/**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

公平地說，這個v很大程度上取決於你的代碼。

我通常喜歡記錄良好的代碼，尤其是在第二個示例中使用的代碼 - 但不是當方法本身是自解釋的時候。

想象一下，Point類聲明瞭x和y變量以及2個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();