How to "Correctly" Comment a program, using different commenting styles and when to use them? [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 8 years ago.

Improve this question

After spending a long time writing (what I like to think of as a nice program), I'm looking to clean up my code, and do some commenting so that its easy to read and looks nice and crisp.

My question is, when do I use the different types of commenting? Block, Single Line, JavaDoc, etc.

For example, if you take my code (just one method). How would I go about commenting it "correctly"

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;
}

Also, if you could give me an example of WHAT I should actually write in these comments, I don't exactly know what is not needed(useless info) vs Useful commenting. If you write a commented example with my code, just guess what the functions do.

All help/suggestions is appreciated. Hopefully this question can help people in the future as well.

Thanks, Sully

Answer 1

You write what another developer needs to know, concisely as possible, in the case that you get hit by a bus.

Or for a year from now, when you need to refactor the whole thing, what you need to not have to relearn everything.

See this:

Technical tips for writing great Javadoc