Java 如何“正确”注释程序，使用不同的注释样式以及何时使用它们？

在花了很长时间编写了我认为不错的程序之后，我希望清理我的代码，并做一些注释，使其易于阅读，看起来又漂亮又清晰

我的问题是，我什么时候使用不同类型的评论？ 块、单行、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;
}

另外，如果你能给我一个例子，说明我应该在这些评论中写些什么，我不知道什么是不需要的无信息和有用的评论。如果你用我的代码写了一个有注释的例子，猜猜函数是做什么的

感谢所有帮助/建议。希望这个问题也能对未来的人们有所帮助

谢谢，

---

萨利

你写下了另一个开发者需要知道的，尽可能简洁，以防你被公共汽车撞到

或者从现在起的一年内，当你需要重构整个东西时，你不需要重新学习所有东西

见此：

---

@JoshM我写的代码，完全理解它。我没有完全理解的是，我应该如何准确地对它进行评论，以使它被认为是干净和有用的，以最好的方式。像这样的简单方法不需要任何评论。但是，您应该通过一些静态分析工具（如FindBugs等）运行代码，因为您有可以减少的未使用变量或范围。