Java interface for comments only. Good practice?

Question

I have a class that has loads of functions, and I can't divide it in multiple class :

Class A {
    // attributes

    /**
     * Descriptive of foo
     *
     * @param i ...
     * @param j ...
    */
    public void foo(int i, double j) {
        ....
    }

    // doc for foo2
    public void foo2() {
        ....
    }

    ....

    // doc for foo8
    public void foo8() {
        ....
    }
}

---

Question is, is it a good practice to make it implement an interface which will take care of the comments ?

/**
 * No function bodies, so there is more place here !
*/
interface AHelper {

    /**
     * Descriptive of foo
     *
     * @param i ...
     * @param j ...
    */
    public void foo(int i, int j);

    // etc
}

/**
 *
 * @see A
*/
class A implements AHelper {

    public void foo(int i, int j) {
        ....
    }

    // etc
}

---

This way, the interface looks the same way as C headers. The idea behind it is having two files with around ~150 lines and not a single file (the Class) with 300 lines.

Answer 1

No, you should not introduce documentation-only interfaces. This removes one of the big advantages of Javadoc: that the docs are right next to the code, which makes it easier to keep them in sync.

Introduce interfaces only because they convey some meaning in your design. If a class is not used through an interface type, what is the point of that interface? Regarding your comparison to C headers: you would not declare and document static helper functions in a header because they are never called across compilation units. They are not part of the abstraction provided by the header file.

Meaningless interfaces do not simplify your code: they makes code more difficult to understand because we have to first figure out that the interface doesn't provide any useful abstraction and is never used.

Also, a 300 line class is well within an acceptable class size, especially if it also contains Javadoc.

Answer 2

I agree with the answer @amon provided and would like to amplify it a little bit.

Generally, it is not a good idea introducing an interface when you have only one implementation of it. And yes, mock classes for your unit tests do count as implementations of an interface.

For further clarification, see Reused Abstraction Principle.

What I like about your question, though, is that it can be seen that you thought about separating the class into several smaller classes (SRP), and that you document your code. Those are good practices. Keep it up.