2

So, unfortunately, I'm stuck with code where I'm doing this:

@Override
method A{
    //calls private methods 1-8
}

private method 1{
    //copy/pasted
}

And so on for all of the private methods. I'd have preferred if the developers of the method I'm overriding had made the private methods protected, but I can't change that now.

All of these private methods have javadoc along with them - should I carry this along with the copy/pasted functions in my class and adjust them accordingly, or not waste my time since it is documented in the original file?

gnat
  • 21,442
  • 29
  • 112
  • 288
Mitch
  • 153
  • 1
  • 1
  • 6
  • Can you be more specific about what you are trying to accomplish and what restrictions you are facing? Why can't you do the obvious and factor out the code into a new class? – kevin cline Jul 31 '14 at 15:32
  • This is in a new class. `class A` contains the original `method A` and now I'm overriding it in `class B`. Unfortunately, I'm overriding it just to change a little thing (and I'm unable to edit the original), so I need copy/paste the original source to the `class B` and make sure that all the private classes the original `method A` in `class A` are also in `class B` – Mitch Jul 31 '14 at 17:14

4 Answers4

2

I would recommend copying the javadoc along with the methods, since anyone looking at this class in the future may very well have no idea that these private methods are really the exact same as those in the originating class.

Also, when the javadoc for the new class is generated, those methods will not have their intended documentation. Plus, what if the implementation in either the original or the copied methods changes independently? It would be very easy for the javadoc to become out of sync.

Finally, since you are simply copying the methods wholesale, it's not really a waste of time to copy the adjacent documentation at the same time.

eldon111
  • 36
  • 1
  • 4
    I would however **add** a remark that this is copied code! All these copies should reference one another for future maintenance. – Jan Doggen Jul 31 '14 at 13:48
0

Could you, instead of copy pasting, just patch the code across as part of your build? If you marked up the start and end of the copied section in a particular comment style and then had a script pull that into your other file ahead of compilation you would have the same outcome but with an automated process.

That is obviously a terrible solution in general, but compared with copy pasting you are at least not having the same code squirrelled away in multiple places, which is almost guaranteed to cause you problems in future.

Also think very hard about whether there isn't some way you could avoid this altogether by thinking laterally about it. It may not be possible, but sometimes a smart solution will present itself.

glenatron
  • 8,729
  • 3
  • 29
  • 43
  • I did in fact think of a better way of doing this in a way that allowed me to just call the overridden method, but thought the question was still a good one so left it up. – Mitch Jul 31 '14 at 16:29
0

For questions like this, I start by answering the question "what makes the code easier to understand for me and my organization?". That's by far the most important consideration.

Bryan Oakley
  • 25,192
  • 5
  • 64
  • 89
0

Just as one does not copy and paste all of the methods from the superclass when writing code, so to should one not copy and paste all of the documentation when documenting overridden methods.

From javadoc at docs.oracle.com:

{@inheritDoc}

Inherits (copies) documentation from the "nearest" inheritable class or implementable interface into the current doc comment at this tag's location. This allows you to write more general comments higher up the inheritance tree, and to write around the copied text.

This tag is valid only in these places in a doc comment:

  • In the main description block of a method. In this case, the main description is copied from a class or interface up the hierarchy.
  • In the text arguments of the @return, @param and @throws tags of a method. In this case, the tag text is copied from the corresponding tag up the hierarchy.

See Automatic Copying of Method Comments for a more precise description of how comments are found in the inheritance hierarchy. Note that if this tag is missing, the comment is or is not automatically inherited according to rules described in that section.

And thus, you inherit the documentation from the superclass. If the superclass documentation updates, yours does too.

Just as with inheritance of code, you can extend the comments.

Lets see what things look like in an IDE and code...

public interface IFace {
    /**
     * This is a method.
     */
    public void method1();

    /**
     * This is also a method
     */
    public void method2();
}

This is just an interface with some javadocs and two methods.

Lets have a class implement this...

public class CClass implements IFace {

    /**
     * {@inheritDoc}
     * This just returns.
     */
    public void method1() {
    }

    public void method2() {
    }
}

And then the javadocs themselves:

public void method1()
This is a method. This just returns.
Specified by:
method1 in interface IFace

img

public void method2()
Description copied from interface: IFace This is also a method
Specified by:
method2 in interface IFace

img

The first thing to see is that with method1, the javadoc is included and extended with the {@inheritdoc}. However, no javadoc will also inherit the javadoc from wherever.

If you are not changing the javadoc, don't specify it. Let the IDE do its thing. Let the automatic javadoc generation do its thing too. Copying and pasting documentation can be just as bad as copying and pasting code as it violates DRY and may lead to the documentation from the superclass or interface getting out of sync with the documentation of the method.

On the other hand, if you are going to write something more, inherit the documentation and write it.

Community
  • 1