CODEWITHSUNDEEP
javadocumentationjavadoc
devoured elysium
devoured elysium

Reputation: 105097

How to deal with JavaDoc comment repetition?

I was wondering what the best way of documenting this potential Point class is:

public class Point {
    /* the X coordinate of this point */
    private int x;
    /* the Y coordinate of this point */
    private int y;

    public Point(int x, int y) {
        this.x = x;
        this.y = y;
    }

    public int getX() {
        return x;
    }

    public int getY() {
        return y;
    }
}

My concrete concern lies with the repetition between the x and y attributes and their respective getters and setters, as well with the constructor arguments.

It's not that I'm developing a public API or anything of the likes, it's no problem for me to have a general comment regarding some variable and then having the getter and setter have just the same text, for instance. I'd just like to avoid comment repetition in my own internal code. Is there a way to tie getX() and the int x argument of the constructor to the x attribute, for instance?

Thanks

Upvotes: 5

Views: 334

Answers (2)

Marcel Stör
Marcel Stör

Reputation: 23535

Is there a way to tie getX() and the int x argument of the constructor to the x attribute, for instance?

No, not that I'm aware of. What I do:

  • don't comment getters (or setters) at all
  • if X needs contextual information and if it somehow represents (part of the) state of the class I document it in the class-level Javadoc only

Upvotes: 1

Alex Krauss
Alex Krauss

Reputation: 10393

One obvious convention would be not writing JavaDoc comments for trivial getters.

Upvotes: 0

Related Questions