Comment the interface, implementation, or both?

Interface vs Implementation: Who Gets the Comment?

When to Comment the Implementation?

Implementation comments are your "special sauce" - detailed when you are dealing with complex logic that is not immediately apparent from the code itself. For situations that require an override of an interface method, adopt the {@inheritDoc} tag. It fetches the interface's documentation and allows you to append additional details specific to the implementation. This not only respects the DRY principles, but also harmonizes comments with your code.

Exhibit A, Inherited Behavior:

public class SimpleCalculator implements Calculator {

  /**
   * {@inheritDoc}
   * This implementation uses the '+' operator.
   * Yes, it's that basic, like Elementary Math 101. No rocket science here!
   */
  @Override
  public int add(int a, int b) {
    return a + b;
  }
}


If you're speaking the C# language, the <inheritdoc/> tag serves a similar purpose to inherit documentation and keep your comments bromantic and synchronized.

Documentation Masterclass

Make Use of Tools and Tags

Consider GhostDoc or ReSharper your coding accomplices - they auto-insert JavaDoc comments rapidly and effortlessly. Alike summoning an espresso shot with "Document This" in GhostDoc, it updates comments efficiently, ensuring they're synchronized with your code, just like how your coffee intake is synchronized with your productivity levels.

Make Implementation Comments Informative

When documenting the implementation, jot down the rationale behind your decision-making process or explain algorithm gymnastics. Side-step comment redundancy by referring back to the interface with a “See interface for documentation” comment when elaboration is unnecessary - just like side-stepping to dessert before your coffee cools down.

Manage the Special Cases

In cases where a class bravely implements multiple interfaces or dares to create a complex hierarchy, document this eccentric behavior.

Coding Clarity & Structure

Make It Intuitive, Make It Right

Prefer code that tells its own story. Strive for implementation clarity that minimizes the need for an overpopulated comment section. Leveraging meaningful variable names, design patterns, and reasonable code structure conveys the necessary information—much like how 'Extra Hot, Double Shot, Caramel Latte' tells everything you need to know about your impending coffee rush.

Keep Code Structure Transparent in Documentation

Display your class structure in your documentation. You're building a clear relationship between the interface and the concrete class, reducing the need for repetitive comments.

Best Practices for Library APIs

Don't Skimp on Public API Commentary

For libraries marketed to other developers, primary focus should be on interface documentation. It's pivotal to maintain detailed and comprehensive documentation that forms the contract that users will interact with.

Documentation Tools to the Rescue

To ensure users get complete information, employ Doxygen or similar tools for generating docs that include comments from interfaces and implementations.