Way to organize repetitive text in Java

Question

Some times I have texts that appears in different places, like comments, messages... For example if I have a custom Exception, probably class doc, messages that passes as parameter to its constructor will have the same phrases (here This exception throws under situation1):

/**
 * This exception throws under situation1 ...
 *
 */
public class SomeException extends Exception {

    public static class Builder{
        String message = "This exception throws under situation1. So ... ";

        public Builder(String message) {
            this.message = this.message + "\r\n" + message;
        }
        public SomeException build(){
            return new SomeException(this);

        }
    }

    private SomeException(String detailMessage) {
        super(detailMessage);
    }

    public SomeException(Builder builder) {
        this(builder.message);
    }
}

And also documents of each method that throw exception will have the same phrase:

/**
 * @throws SomeException
 *             This exception throws under situation1 ...
 */
private void test() throws SomeException {
    throw new SomeException.Builder("message").build();
}

If I copy/paste phrase, maintenance of documents will be hard (it needs finding and updating all repeats on each edit).

To solve this, I can use a constant string that its value and its comment are those repetitive terms

 /**
  * exception throws under situation1
  */
public static final String CONSTANT = "exception throws under situation1";

and reference to it (and it's comment):

/**
 * {@link MyClass#CONSTANT}
 */
String message = MyClass.CONSTANT;

But how organize constants when are more than one? With respect to this answer and this one, it seems the best way to organize them is using Enum:

public enum Meta {
    /**
     * exception throws under situation1
     */
    CONSTANT("exception throws under situation1");

    private String text;

    Meta(String text) {
        this.text = text;
    }

    public String getText() {
        return this.text;
    }

}

But is there a better way than this? Especially it complicates code.

Answer 1

It's repetitive because it's redundant.

The right way to "organize it" is by removing it.

/**
 * This exception throws under situation1 ...
 */
public class SomeException extends Exception {

"This"? I know that Javadoc refers to this class, and not some other one.

"Exception"? I can very well see that this is an Exception.

"Throws"? It goes without saying that exceptions are to be thrown.

/**
 * Stuff went bad as in [situation1]
 */
public class SomeException extends Exception {

That's enough. Cut the obvious out.

/**
 * @throws SomeException
 *             This exception throws under situation1 ...
 */
private void test() throws SomeException {
    throw new SomeException.Builder("message").build();
}

And what's the point of copy-pasting the same stuff here?

I can look up the Javadoc for SomeException. That's exactly what it is for.

Don't repeat the general info about it.

If there is something specific about SomeException in the context of your test method, put it in Javadoc, by all means!

But then it would be a unique piece of information, by definition.

And if it's merely copy-pasta, then leave it.

All it does is littering your code with noise.

I know that many programmers think they serve a noble cause by striving for 100% Javadoc coverage, and they take pride to produce code like:

/**
 * Sets name
 * @param name - name 
 */
public void setName(String name) {
    this.name = name;
}

Just stop it. It's pointless.

Okay, it's a bit different if you're writing a library (most of the time that's not the case, and nothing in your question indicates this is what you are doing). But anyhow, only a bit different. Redundancy is a red flag. Valuable information is specific. If the information you provide is not, it's probably not that valuable. So it's better to either leave it out altogether, or make it more contextual.

Answer 2

Put your strings into a ResourceBundle, as though you were internationalizing the application. There are a number of tutorials out there for doing this sort of thing, but for the most part they boil down to exactly the problem you're describing: putting text into a common location, where you can later refer to it by an identifier of some kind.

People often think of this solely in terms of making it easier to translate an application into other languages, but it is also useful for situations like this, where you have to repeat the same message many times. As an added bonus, when and if you do decide to internationalize the app, the basic infrastructure will already be in place. All you'll have to do is add more languages.