Interface Documentation
Някой би ли подсказал как се пише документация на интерфейс, съдържащ 1 метод? В домашното от Code Documentation and Comments се сбъсках с подобен проблем и не намерих адекватни отговори в нета. Истината, е че ако този 1 метод е наименуван добре коментара е излишен. Мъча се да не пиша документация на интерфейс от 3 думи, еднакви с коментара на метода в него. Същото се отнася и за методи с 1 пропърти..., но според задачата "Document all public interfaces". Ще съм благодарен за някаква насока.
За методите съм съгласен, но при положение, че в интерфейса има 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);
}
}
Според мен не е редно да описваш какво точно съдържа интерфейса, а каква е целта му. IRenderer по същество е интерфейс, който описва поведението на класове, които могат да рендерират някакъв текст някъде (зависи вече от имплементацията къде е това някъде). Отново, разгледай интерфейсите в .NET, там има описания под формата на коментари, примерно:
Interface: IList
Purpose: Base interface for all generic lists.
Има и допълнителни обяснения малко по-надолу, например:
Т.е. по-скоро насочи вниманието не какво има вътре, какви точно методи, а каква е задачата им. Според single responsibility принципа един интерфейс трябва да има една задача, съответно в документацията твоята цел е да опишеш тази задача по по-общ начин.