Java Interfaces – Is It Good Practice for Comments Only?

interfacesjava

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.

Best Answer

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.

Related Topic