CODEWITHSUNDEEP
javajavadoc
Matheus Popst de Campos
Matheus Popst de Campos

Reputation: 149

Is there any javadoc tag like "must avoid"?

I am writing a method that is a little overpowered and I want to throw a warning to my user telling him to "better know what you're doing", just like the way @deprecated behaves. I can write this one the method name, but I wonder if there is a more elegant way of doing this.

public class Divison {

public Divison() {
}

private int up;
private int down;


public int eval() {
    return ((int) up/down);
}

public void setVars(int up, int down) {
    this.up = up;
    if (up%down == 0) {
        this.down = down;
    } else {
        throw new ArithmeticException("the values must be divisible");
    } 
}

public void betterKnowWhatYouDoingSetVars(int up, int down) {
    this.up = up;
    this.down = down;
}

}

Upvotes: 1

Views: 182

Answers (1)

Costi Ciudatu
Costi Ciudatu

Reputation: 38205

Allowing the outer world to break your invariants is never a good idea, as your class becomes useless: since I can't rely on its internal state being consistent, it's just a bag of values unrelated to each other. To write correct programs, I would need to replicate all your validation logic inline before every usage of that class.

By the way, your example implementation can get in an inconsistent state even without the betterKnowWhatYoureDoing... method, and I'm not even mentioning multi-threading. You can prevent that by simply making the class immutable and doing that check in the constructor.

I think you should thoroughly re-evaluate your design before going this route.

If you must provide such functionality (I can hardly imagine any reason why), at least make it package-private (instead of public and documented as "dangerous").

Also, those who really know what they're doing are probably never going to call that method anyway, so it's a bit pointless... :)

Upvotes: 1

Related Questions