2

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.

  • Just want to ask, do you know that the reason the Javadoc concept was created was to allow details in the source code to then be converted into a browsable web interface like you see when you view the Java SE API? – Jahhein Oct 16 '17 at 9:52
  • 2
    A low lines-of-code count isn't a value in itself (otherwise writing everything into one very long text line would be a good solution!?), a long class is a hint that it might be better broken into single-responsibility pieces. It's just a hint, and you already analyzed that. So keep the 300 lines of code! – Ralf Kleberhoff Oct 16 '17 at 12:30
  • 1
    In addition to SRP, use the oodesign.com/interface-segregation-principle.html and properly JavaDoc the interface. – Martin Spamer Oct 17 '17 at 2:29
  • @Jahhein No, that's not why they were created, although that is one of the use-cases. JavaDocs, at least in the case of Java SE, exist for specification reasons - they define the contract for which implementors must follow, not the other way around. "Our documentation comments define the official Java Platform API Specification" :: "there are commonly two different ways to write doc comments -- as API specifications, or as programming guide documentation" – Vince Emigh Oct 21 '17 at 23:05
17

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.

  • This answer is wrong because it violated the interface segregation principle and the JavaDoc represents the contract, not the implementation. oodesign.com/interface-segregation-principle.html – Martin Spamer Oct 17 '17 at 13:36
  • @MartinSpamer I do not see how the ISP applies here. “Clients should not depend on interfaces they don't use” means that interfaces should be sufficiently granular and that God Objects should be avoided. It does not by itself imply that contracts should be declared separately from their implementation, i.e. that we should use interfaces for everything. In particular, my answer argues that it is harmful to use Java interfaces as a mechanism to split up your source files, as opposed using interfaces in order to implement a particular design (which of course should adhere to the ISP). – amon Oct 17 '17 at 13:49
6

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.