Java – Is Repeating Links to the Same Class in a Single Javadoc Comment a Bad Practice?

coding-styledocumentationjavajavadocsprogramming practices

I'm currently writing an API and its documentation. For example I have something like this:

public interface Event {
}

public interface Process {
}

public interface EventProcessor {
    /**
     * Starts to process the sepcified event asynchronously. The returned
     * {@link Process} can be used to track progress on the processing. If the
     * specified event causes more {@link Event events} to be processed in this
     * system, then they are also tracked via the returned {@link Process}.
     * 
     * @param event
     *            to be started to process
     * @return
     */
    Process startProcessing(Event event);
}

In the example above, the javadoc link to the interface Process is repeated. In the API I'm writing there are cases where I have several more references to the same class in a single javadoc comment.

Should I always mark references to the class/method/etc. as javadoc links?

Generally, I think having many links in a javadoc comment is a sign for high cohesion. But when it's often the same target, which is linked, I'm not sure if this is good.

Best Answer

Here is what the oracle javadoc guidelines say:

Use in-line links economically
You are encouraged to add links for API names (listed immediately above) using the {@link} tag. It is not necessary to add links for all API names in a doc comment. Because links call attention to themselves (by their color and underline in HTML, and by their length in source code doc comments), it can make the comments more difficult to read if used profusely. We therefore recommend adding a link to an API name if:

The user might actually want to click on it for more information (in your judgment), and

Only for the first occurrence of each API name in the doc comment (don't bother repeating a link)

Our audience is advanced (not novice) programmers, so it is generally not necessary to link to API in the java.lang package (such as String), or other API you feel would be well-known.

So summarized, repeating links to the same link target is a bad practice.

Thanks to @AaronKurtzhals for pointing me there.

But callers need to construct a `FooManager` before they can initialize it, e.g. because the `FooManager` is passed around as a dependency.

Don't create a FooManager if you don't have one. What you can do instead is pass an object around that lets you retrieve a fully constructed FooManager, but only with the initialization information. (In functional-programming speak, I'm suggesting you use partial application for the constructor.) E.g.:

ctorArgs = ...;
getFooManager = (initInfo) -> new FooManager(ctorArgs, initInfo);
...
getFooManager(myInitInfo).fooMethod();

The problem with this is that you have to supply the init info every time you access the FooManager.

If it's necessary in your language, you can wrap the getFooManager() operation in a factory-like or builder-like class.

I really want to do runtime checks that the `initialize()` method was called, rather than using a type-system-level solution.

It is possible to find a compromise. We create a wrapper class MaybeInitializedFooManager that has a get() method that returns the FooManager, but throws if the FooManager wasn't fully initialized. This only works if the initialization is done through the wrapper, or if there is a FooManager#isInitialized() method.

class MaybeInitializedFooManager {
  private final FooManager fooManager;

  public MaybeInitializedFooManager(CtorArgs ctorArgs) {
    fooManager = new FooManager(ctorArgs);
  }

  public FooManager initialize(InitArgs initArgs) {
    fooManager.initialize(initArgs);
    return fooManager;
  }

  public FooManager get() {
    if (fooManager.isInitialized()) return fooManager;
    throw ...;
  }
}

I don't want to change the API of my class.

In that case, you'll want to avoid the if (!initialized) throw; conditionals in each and every method. Fortunately, there is a simple pattern to solve this.

The object you provide to users is just an empty shell that delegates all calls to an implementation object. By default, the implementation object throws an error for each method that it wasn't initialized. However, the initialize() method replaces the implementation object with a fully-constructed object.

class FooManager {
  private CtorArgs ctorArgs;
  private Impl impl;

  public FooManager(CtorArgs ctorArgs) {
    this.ctorArgs = ctorArgs;
    this.impl = new UninitializedImpl();
  }

  public void initialize(InitArgs initArgs) {
    impl = new MainImpl(ctorArgs, initArgs);
  }

  public X foo() { return impl.foo(); }
  public Y bar() { return impl.bar(); }
}

interface Impl {
  X foo();
  Y bar();
}

class UninitializedImpl implements Impl {
  public X foo() { throw ...; }
  public Y bar() { throw ...; }
}

class MainImpl implements Impl {
  public MainImpl(CtorArgs c, InitArgs i);
  public X foo() { ... }
  public Y bar() { ... }
}

This extracts the main behaviour of the class into the MainImpl.

Best Answer

Related Solutions

Java Development – How to Flag a Class as Under Development

Class Design – How to Warn Other Programmers of Class Implementation

But callers need to construct a FooManager before they can initialize it, e.g. because the FooManager is passed around as a dependency.

I really want to do runtime checks that the initialize() method was called, rather than using a type-system-level solution.

I don't want to change the API of my class.

Related Topic

But callers need to construct a `FooManager` before they can initialize it, e.g. because the `FooManager` is passed around as a dependency.

I really want to do runtime checks that the `initialize()` method was called, rather than using a type-system-level solution.