Софтуерно Инженерство
Loading...
+ Нов въпрос
radoslav_d avatar radoslav_d 12 Точки

Interface Documentation

Някой би ли подсказал как се пише документация на интерфейс, съдържащ 1 метод? В домашното от Code Documentation and Comments се сбъсках с подобен проблем и не намерих адекватни отговори в нета. Истината, е че ако този 1 метод е наименуван добре коментара е излишен. Мъча се да не пиша документация на интерфейс от 3 думи, еднакви с коментара на метода в него. Същото се отнася и за методи с 1 пропърти..., но според задачата "Document all public interfaces". Ще съм благодарен за някаква насока.

1
C# OOP Advanced 05/01/2016 17:40:34
Filkolev avatar Filkolev 4501 Точки

Идеята е това, което името на метода казва с няколко думи, да го обясниш с едно-две изречения.

И на мен на моменти ми е трудно, почвам да се чувствам като на контролно по литература в гимназията, където разтягах локуми. Опитай да го обясниш кратко, но все пак да добавиш нещо, което може да не е веднага очевидно от името на метода.

Разгледай официалната документация на вградените методи за вдъхновение. Пишеш някой метод и гледаш VS какъв туултип ще ти изкара. Хем методите са добре именувани и самодокументирани, хем има и документация, която внася повече яснота.

1
radoslav_d avatar radoslav_d 12 Точки

За методите съм съгласен, но при положение, че в интерфейса има 1 метод и нищо друго и този метод има коментар (и е self-documented), каква документация на интерфейса да напиша? Пример: (по-малко от 15 реда код :) )

    /// <summary>
    /// Holds a method for printing messages to the user.
    /// </summary>
    public interface IRenderer
    {
        /// <summary>
        /// Prints a message to the user.
        /// </summary>
        /// <param name="message"></param>
        /// <param name="parameters"></param>
        void Print(string message, params object[] parameters);
    }
}

1
Filkolev avatar Filkolev 4501 Точки

Според мен не е редно да описваш какво точно съдържа интерфейса, а каква е целта му. IRenderer по същество е интерфейс, който описва поведението на класове, които могат да рендерират някакъв текст някъде (зависи вече от имплементацията къде е това някъде). Отново, разгледай интерфейсите в .NET, там има описания под формата на коментари, примерно:

Interface:  IList
Purpose: Base interface for all generic lists.

Има и допълнителни обяснения малко по-надолу, например: 

// An IList is an ordered collection of objects.  The exact ordering
// is up to the implementation of the list, ranging from a sorted
// order to insertion order.  

Т.е. по-скоро насочи вниманието не какво има вътре, какви точно методи, а каква е задачата им. Според single responsibility принципа един интерфейс трябва да има една задача, съответно в документацията твоята цел е да опишеш тази задача по по-общ начин.

1