Комментарии

Комментарии в C# оформляются в стиле С/С++. Они могут быть однострочными и многострочными.

Однострочные комментарии отделяются от кода двумя символами косой черты:

// Однострочный комментарий

Все что находится после символов косой черты не обрабатывается компилятором, и никак не влияет на остальной код.

Многострочные комментарии определяются символами:
/* начало многострочного комментария,
*/ конец многострочного комментария.

/* Многострочный комментарий размещается на одной */
/* или нескольких
   строках */

Многострочные комментарии не обязательно должны находиться отдельно от остального кода. Их можно вставлять в любом месте. Например можно добавить комментарий внутри определения цикла:

for ( int i; /* счетчик цикла */ i < 10; i++ ) {
}

XML-комментарии. Документирование кода.

Для документирования кода в C# используются документирующие комментарии или XML-комментарии. Как и в случае с обычными комментариями, XML-комментарии могут быть однострочными и многострочными.

Однострочные XML-комментарии начинаются с трех обратных наклонных черт ( /// ). Как и обычные комментарии они должны быть расположены на одной строке. Если для документирования кода используется несколько строк, то каждая из них должна начинаться с трех слешей ( /// ).

Многострочные XML-комментарии начинаются символами /**, а заканчиваются символами */.

Для документирования сущностей C# внутри XML-комментариев используются специальные теги, основные из них перечислены в таблице:

Тег XMLОписание тега
<summary>Описывает основные функции сущности. Его можно добавлять к типам или членам типов.
<remarks>Дополнительные пояснения к какой-либо сущности.
<returns>Описывает значение, которое должен возвращать метод.
<value>Описывает значение, предоставляемое свойством.
<exception>Описывает исключение, генерируемое методом.
<see>, <seealso>Ссылка на документацию.
<param>Описывает параметры, передаваемые методу. Применяется вместе с атрибутом name, при помощи которого задается имя описываемого параметра.

Пример использования тегов в XML-комментариях:

namespace Samples {
    /// <summary>
    /// Класс описывающий прямоугольник
    /// </summary>
    public class Rectangle {  
        /// <summary>
        /// В описании этого конструктора могла бы быть ваша реклама
        /// </summary>      
        /// <param name="x">X левого правого угла</param>
        /// <param name="y">Y левого правого угла</param>
        /// <param name="width">Ширина прямоугольника</param>
        /// <param name="height">Высота прямоугольника</param>
        public Rectangle( double x, double y, int width, int height ) {
            X = x;
            Y = y;
            Width = width;
            Height = height;
        }

        /// <value>
        /// Координата X левого верхнего угла прямоугольника
        /// </value>
        public double X { get; set; }

        /// <value>
        ///  Координата Y левого верхнего угла прямоугольника
        /// </value>
        public double Y { get; set; }

        /// <value>
        /// Получение или установка ширина прямоугольника
        /// </value>
        public double Width { get; set; }

        /// <value>
        /// Получение или установка высоты прямоугольника
        /// </value>
        public double Height { get; set; }

        /// <summary>
        /// Метод, определяющий попадание в границы прямоугольника
        /// </summary>
        /// <param name="x">Координата X нажатия левой кнопки мыши</param>
        /// <param name="y">Координата Y нажатия левой кнопки мыши</param>
        /// <returns>Возвращает true, если клик рядом с границей</returns>
        public bool IsHitingToBorder( double x, double y ) {
            return ( ( x >= X ) &&
                    ( y >= Y ) &&
                    ( x <= X + Width ) &&
                    ( y <= Y + Height ) )
                   &&
                   ( ( x <= X ) ||
                    ( y <= Y ) ||
                    ( x >= X + Width ) ||
                    ( y >= Y + Height ) );
        }
    }
}
avatar
5000
  Подписаться  
Уведомление о