Комментирование кода: интерфейса, его реализации или обоих?

Быстрый ответ

Комментируйте интерфейс, определяя таким образом условия контракта, который он заключает. Для методов в интерфейсе используйте JavaDoc, что позволит четко описать их цель, параметры и результат работы. Взгляните на пример:

/**
 * Операции калькулятора.
 */
public interface Calculator {

  /**
   * Складывает два целых числа.
   *
   * @param a первое слагаемое, например, количество выпитого утром кофе
   * @param b второе слагаемое, например, число выполненных задач за день
   * @return сумма a и b, которую можно рассматривать как индикатор продуктивности
   */
  int add(int a, int b);
}

Комментарии к реализации, подобные идеально приготовленному эспрессо, должны быть сжатыми, но содержательными. Код должен быть самодокументированным по возможности, а комментарии следует оставлять только для объяснения сложных или нетривиальных участков. Помните о золотом правиле: обновляйте документацию, также как вы заботитесь о своей кофемашине.

Интерфейс и реализация: кому какие комментарии?

Когда стоит комментировать реализацию?

Комментарии к реализации помогают вашему коду выразить уникальность, когда речь идет о сложной логике, неявной в коде. При переопределении метода интерфейса может быть полезным использовать тег {@inheritDoc}, позволяющий наследовать документацию интерфейса и дополнять её специфическими уточнениями для данной реализации. Это не только помогает избежать избыточности, следуя принципу DRY, но и создает гармоничное взаимодействие между кодом и комментариями.

Пример с унаследованным поведением:

public class SimpleCalculator implements Calculator {

  /**
   * {@inheritDoc}
   * Данный метод просто складывает числа с помощью оператора '+'.
   * Да, все реализовано просто, как основные правила математики, которые мы узнали в школе.
   */
  @Override
  public int add(int a, int b) {
    return a + b;
  }
}

Если вы программируете на C#, тег <inheritdoc/> выполняет аналогичную функцию, давая возможность наследовать документацию и поддерживать комментарии в актуальном и согласованном виде.

Мастер-класс по документированию

Инструменты и теги

GhostDoc и ReSharper будут вашими верными помощниками в процессе написания кода – они помогут вам быстро и без проблем вставлять JavaDoc комментарии. Точно так же, как инструмент "Document This" в GhostDoc помогает обновлять комментарии, так и вы сможете эффективно синхронизировать их с кодом.

Информативные комментарии к реализации

Документируя реализацию, не забывайте описывать логику принятых решений или используемые алгоритмические приёмы. Если детальное описание не требуется, ссылайтесь на интерфейс с помощью комментария «См. документацию интерфейса», экономя таким образом время и место.

Особые случаи

При реализации некольких интерфейсов одним классом или формировании сложной иерархии комментируйте данные особенности поведения.

Визуализация

Давайте вкратце подведем итоги правил комментирования в Java:

📚 Интерфейс:
  – ОПИСАНИЕ контракта,
  – ЦЕЛЬ каждого метода,
  – ПАраметры метода и ВОЗВРАЩАемое значение описаны.

📘 Реализация:
  – ИСПОЛНЕНИЕ контракта,
  – Описание ЛОГИКИ выполнения и алгоритма,
  – Указание на ОСОБЕННОСТИ выполнения и моменты производительности.

Четкое значение кода и структура

Интуитивно понятный и корректный код

Ваш код должен говорить сам за себя. Правильная структура классов и хорошо подобранные имена переменных, паттерны проектирования – всё это поможет в понимании работы кода.

Прозрачность структуры в документации

Ваша документация должна отражать структуру класса, что позволит уменьшить количество повторений в комментариях.

Лучшие практики для публичных API библиотек

Подробные комментарии для публичных API

Если вы разрабатываете библиотеку для иных разработчиков, важно особенно внимательно подходить к документированию API.

Инструменты для документации

Воспользуйтесь Doxygen или аналогичными инструментами для создания полной и соответствующей действительности документации из комментариев интерфейсов и реализаций.

Полезные материалы

1. [Effective Java, 3rd Edition [Книга]](https://www.oreilly.com/library/view/effective-java-3rd/9780134686097/) — знаменитое руководство по Java от Джошуа Блоха, включающее рекомендации по комментированию кода.
2. Как составлять комментарии для Javadoc — официальное руководство Oracle по написанию JavaDoc.
3. Простые комментарии для геттеров и сеттеров – Stack Overflow — обсуждение на Stack Overflow о JavaDoc и его лучших практиках.
4. DZone – Лучшие практики JavaDoc и комментирования — стратегии комментирования от DZone.
5. API Spring Framework 6.1.3 — пример комментирования интерфейсов и реализаций в документации API Spring Framework.