TOC

This article is currently in the process of being translated into Russian (~35% done).

Основы:

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  
{
......

Use the start sequence of forward-slash-asterisk (/*), write whatever you like, across multiple lines or not, and then end it all with the end sequence of asterisk-forward-slash (*/). In between these markers, you can write whatever you want.

As with pretty much any other programming related subject, whether to use multiple single-line comments or one multi-line comment is often debated. Personally, I use both, for various situations - in the end, it's all up to you!

Documentation comments

Documentation Comments (sometimes referred to as XML Documentation Comments) looks like regular comments, but with embedded XML. Just like with regular comments, they come in two forms: Single-line and multi-line. You also write them the same way, but with an extra character. So, single-line XML Documentation Comments uses three forward slashes (///) instead of two, and the multi-line variant gets an extra asterisk added in the start delimiter. Let's see how it looks:

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; }
}

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

Documenting your types and their members with documentation comments is a pretty big subject, and therefore it will be covered more in depth in a later article, but now you know how they look!

Code comments & the Task list

If you're using Visual Studio, you can actually get some help tracking your code comments. In the Task List window (access it from the menu View > Task List) your comments will appear if they use the special, but very simple Task List comment syntax:

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

So if the single-line comment is immediately followed by TODO or HACK, it will appear in the Task List of Visual Studio, like this:

And there are more types - depending on the version of Visual Studio you're using, it will respond to some or all of the following comment tokens:

  • TODO
  • HACK
  • NOTE
  • UNDONE

You can even add your own tokens, if you want to - just follow the steps described in this article.

Summary

Code comments are extremely useful in documenting your code or for the purpose of leaving clues to your self or your potential colleagues on how stuff works. As an added benefit, they're great when you need to test something quickly - just copy a line and comment out the original line and you can see how it works now. If you're not happy with the result, you can just delete the new line and uncomment the original line and you're back to where you started.

And don't worry about the end-user snooping through your comments - they are, as already mentioned, completely ignored by the compiler and therefore not in anyway included in your final DLL or EXE file. Code comments are your personal free-space when programming, so use it in any way you want to.

This article has been fully translated into the following languages: Is your preferred language not on the list? Click here to help us translate this article into your language!