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 4482 Точки

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

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

Разгледай официалната документация на вградените методи за вдъхновение. Пишеш някой метод и гледаш 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 4482 Точки

Според мен не е редно да описваш какво точно съдържа интерфейса, а каква е целта му. 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
Можем ли да използваме бисквитки?
Ние използваме бисквитки и подобни технологии, за да предоставим нашите услуги. Можете да се съгласите с всички или част от тях.
Назад
Функционални
Използваме бисквитки и подобни технологии, за да предоставим нашите услуги. Използваме „сесийни“ бисквитки, за да Ви идентифицираме временно. Те се пазят само по време на активната употреба на услугите ни. След излизане от приложението, затваряне на браузъра или мобилното устройство, данните се трият. Използваме бисквитки, за да предоставим опцията „Запомни Ме“, която Ви позволява да използвате нашите услуги без да предоставяте потребителско име и парола. Допълнително е възможно да използваме бисквитки за да съхраняваме различни малки настройки, като избор на езика, позиции на менюта и персонализирано съдържание. Използваме бисквитки и за измерване на маркетинговите ни усилия.
Рекламни
Използваме бисквитки, за да измерваме маркетинг ефективността ни, броене на посещения, както и за проследяването дали дадено електронно писмо е било отворено.