Code Comments

При написании кода вы быстро привыкнете к тому, что большинство слов и символов имеют особое значение. Например в C#, вы увидите различные ключевые слова, такие как: class, namespace, public и т.д. Вы заметите, что компилятор будет следить за их правильным использованием, точно так-же как он следит за использованием вами ваших методов и переменных. C# — довольно строгий язык, но компилятор поможет вам ввести всё правильно и укажет на ошибку если вы её допустите. Тем не менее существует один способ писать что угодно благодаря комментариям.

Возможно вы уже сталкивались с комментариями в коде. Будь то C# или другой язык программирования - концепция комментариев довольно универсальна. Давайте же рассмотрим какие типы комментариев бывают в C# и как их использовать.

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

Самый простой и наиболее распространённый тип комментария в C# — однострочный комментарий. Как вы наверно догадываетесь из его названия, он превращает в комментарий одну строчку. Давайте посмотрим как это выглядит на примере:

// My comments about the class name could go here...
class Program
{
    ......

Всё просто: добавьте в начале строки две косые черты ( "//" ) и ваша строчка перестанет интересовать компилятор от слова "совсем" — теперь это комментарий! А если вам понадобится больше одной строки для записей, вы легко можете закомментировать этим способом несколько строк подряд:

// My comments about the class name could go here...
// Add as many lines as you would like
// ...Seriously!
class Program
{
    ...... 

Многострочные комментарии

Если вы хотите комментировать несколько строк кода как единый блок, то имеет смысл использовать многострочные комментарии. Всё, что находится между этими символами /* */ - игнорируется:

/*  
My comments about the class name could go here...  
Add as many lines of comments as you want  
    ...and use indentation, if you want to!  
*/  
class Program  
{
    ......

Используйте начальный маркер комментария, состоящий из слеша и звездочки (/*), а затем, где вам угодно, через несколько строк или нет, закончите комментарий с помощью конечного маркера комментария, состоящего из звездочки и слеша после нее (*/). Пишите что угодно между двумя этими маркерами, это будет считаться комментарием.

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

Документационные комментарии

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

class User
{
    /// <summary>
    /// The Name of the User.
    /// </summary>
    public string Name { get; set; }

    /**
    * <summary>The Age of the User.</summary>
    */
    public string Age { get; set; }
}

Здесь вы можете увидеть оба варианта - однострочные и многострочные комментарии. Действие одинаково, но первый вариант чаще используется для документирования.

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

Комментарии кода и список задач

Если вы используете Visual Studio, то можно облегчить работу с комментариями. В окне Список задач (можно получить доступ через меню Вид > Список задач) появятся ваши комментарии, если они используют специальный, но в тоже время очень простой синтаксис списка задач:

//TODO: Change "world" to "universe"
Console.WriteLine("Hello, world!");
//HACK: Don't try this at home....
int answerToLife = 42;

Таким образом, если однострочный комментарий начинается с TODO или HACK, то он будет вот так отображен в Списке задач Visual Studio:

И существуют некоторые другие типы - в зависимости от версии, которую вы используете, Visual Studio будет работать с некоторыми или даже всеми обозначениями:

• TODO
• HACK
• NOTE
• UNDONE

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

Резюме

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

И не волнуйтесь, что конечный пользователь будет читать ваши комментарии - они, как сказано ранее, полностью игнорируются компилятором и, следовательно, в любом случае не будут включены в итоговый EXE или DLL файл. Комментарии в коде это ваше персональное пространство во время программирования, так что используйте их так, как вам угодно.