Home/ Questions/Q 808959
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-05-15T00:38:58+00:00

I have a question about where to document logic in javadocs. For example, I

  • 0

I have a question about where to document logic in javadocs. For example, I have the following method signature in an interface:

public int getTotalAssociationsAsParent(Long id, Long type);

The method returns associations where the given ID is the parent and the association is of type ‘type’. ID is required, but if type passed in is NULL, then I will return ALL associations where the ID is the parent.

My question is where should this type of logic be documented? I hesitate putting it in the javadoc of the interface because that sort of constrains all implementing classes to adhere to that logic. Maybe in the future, I’ll have an Impl class that throws an IllegalArgumentException if type is NULL.

However, if I put it in non-javadoc in the Impl class, then consumers of this method won’t know how the method behaves with a NULL type.

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    What you describe is the interface contract of the method, so it belongs to the Javadoc indeed. Clients of the interface need to know the exact contract this interface fulfills. If a derived class implements the method differently, it effectively breaks the contract, thus breaks the Liskov Substitution Principle.

    However, if you feel there really is place for different implementations of this method, you have some choices:

    • rethink your design – maybe those implementations should not be in subclasses of the same interface, or maybe you need two distinct methods in that interface
    • define the contract loosely to allow some variance in implementation (but only if it makes sense from the clients’ perspective!)
    • 0