Должны ли вы писать комментарии XML для интерфейсов, конкретных реализаций или обоих?

Название довольно много говорит обо всем. Где я могу применить свои комментарии к XML? Должен ли я помещать более общий XML-комментарий в интерфейс и более описательный в классе реализации? Вот так:

public interface IObjectRepository
{
    /// <summary>
    ///    Returns an object from the respository that contains the specified ID.
    /// </summary>
    Object GetObject(int Id);
}

public ObjectRepository : IObjectRepository
{
    /// <summary>
    ///    Retrieves an object from the database that contains the specified ID.
    /// </summary>
    public Object GetObject(int Id)
    {
        Object myData = // Get from DB code.
        return myData;
    }
}

Я не включил <param> для простоты.

Это хорошая практика для комментариев или есть другой способ? Я просто прошу прокомментировать интерфейс? Любая помощь приветствуется.

Ответ 1

Вы можете определить комментарий в отдельном файле, а затем использовать тег <include> (см. MSDN). Таким образом, вы можете написать комментарий только один раз, но включить его в документацию в нескольких разных местах (например, декларация и реализация интерфейса).

Конечно, для этого требуется немного больше дисциплины, потому что писать труднее. Это также немного менее полезно, потому что вы не увидите их в исходном коде. Однако, если вы хотите использовать комментарии XML для создания документации, то это, вероятно, хороший подход.

Ответ 2

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

Суть заключается в том, чтобы ошибиться на стороне большей ясности, а не меньше.

Ответ 3

Документируйте интерфейсы.

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

Если реализация не отличается от интерфейса, вы можете использовать <inheritdoc />.

Связано: Наследовать документацию на С#?