如何「正確」評論一個程序，使用不同的評論風格以及何時使用它們？

-5

花了很長時間的寫作（我喜歡認爲是一個很好的程序）後，我正在尋找清理我的代碼，並做一些評論，使其易於閱讀，看起來不錯，很清脆。如何「正確」評論一個程序，使用不同的評論風格以及何時使用它們？

我的問題是，我什麼時候使用不同類型的評論？塊，單行，JavaDoc等

例如，如果你拿我的代碼（只是一種方法）。我怎麼會去評論它「正確」

public static String decipher(String cipherText, String key, 
     String originalKey) { 

    String cipher = cipherText; 
    String plainText; 
    int currentLetter; 
    int cl = 0; 

    StringBuilder deciphered = new StringBuilder(); 

    while (deciphered.length() != key.length()) { 

     for (int x = 0; x < cipherText.length(); x++) { 
      String plaintextVal; 
      Character cipherChar = cipherText.charAt(x); 
      Character keyChar = key.charAt(x); 
      String currentCipherLetter = cipherChar.toString(); 
      String currentKeyLetter = keyChar.toString(); 
      int cipherVal = letters.indexOf(currentCipherLetter) + 1; 
      int keyVal = letters.indexOf(currentKeyLetter) + 1; 
      if (cipherVal - keyVal < 0) { 
       int negativeVal = cipherVal - keyVal; 
       plaintextVal = letters.get((cipherVal - keyVal - 1) + 26); 

      } else if (cipherVal - keyVal - 1 < 0 && cipherVal - keyVal > 0) { 
       plaintextVal = letters.get(0); 

      } else if (cipherVal - keyVal == 0) { 
       plaintextVal = letters.get(25); 
      } else { 
       plaintextVal = letters.get(cipherVal - keyVal - 1); 
      } 

      deciphered.append(plaintextVal); 

     } 

    } 

    plainText = deciphered.toString(); 
    System.out.println(cipherText + "/" + originalKey + " = " + plainText); 
    return plainText; 
}

而且，如果你能給我什麼，我應該在這些意見實際上寫一個例子，我不知道到底是不是需要什麼（無用信息） vs有用的評論。如果您使用我的代碼編寫了一個註釋示例，那麼請猜測這些函數的功能。

所有幫助/建議表示讚賞。希望這個問題也能幫助未來的人們。

感謝，蘇利

來源

2014-01-06 Sully Brooks

@JoshM我寫的代碼，並完全理解它。我沒有完全掌握的是我應該如何評論它，以便它以最好的方式被認爲是乾淨和有用的 –

這種簡單的方法不需要任何評論。但是，您應該通過一些靜態分析工具來運行您的代碼， FindBugs等，因爲您有可以減少的未使用的變量或範圍。 – JRL