Книга: C# для профессионалов. Том II

Комментарии

Комментарии

Комментирование кода всегда важно, поэтому дальше в обоих примерах (или первое, что делается в примере на C#) добавляется комментарий:

// Обработчик событий нажатия пользователем кнопки Show Results.
// Выводится квадратный корень и знак числа
private void OnClickShowResults(object sender, System.EventArgs e) {

В VB для обозначения начала комментария используется апостроф, а комментарий продолжается до конца строки. Комментарии в C# в этом коде действуют таким же образом, за исключением того, что начинаются с двух прямых наклонных черт: //. Также как и для комментариев VB, можно использовать всю строку или добавить комментарий в конце строки:

// Этот код определяет результаты
int Result = 10 * Input; // получение результата

Однако C# более гибок в своих комментариях, так как позволяет использовать два других способа указания комментариев, каждый из которых имеет слегка различный эффект.

Комментарий также может быть ограничен последовательностями символов /* и */. Другими словами, если компилятор встречает последовательность /*, он предполагает, что весь последующий текст является комментарием, пока не встретит последовательность */. Это позволяет иметь длинные комментарии, которые распространяются на несколько строк:

/* этот текст действительно является длинным
длинным
длинным
длинным
комментарием * /

Короткие комментарии внутри строки являются очень полезными, если необходимо только временно заменить что-то в строке во время отладки:

X = /* 20 */ 15;

Третий способ похож на первый. Однако теперь используется три слэша:

/// <summary>
/// Event handler for user clicking Show Results button.
/// Displays square root and sign of number
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void OnClickShowResults(object sender, System.EventArgs e)

Если впереди используются три наклонные черты вместо двух, то комментарий по-прежнему продолжается до конца строки. Однако этот комментарий имеет теперь дополнительный результат: компилятор C# способен на самом деле использовать комментарии, которые начинаются с трех наклонных черт, чтобы автоматически создавать документацию для исходного кода как отдельный файл XML. Именно поэтому пример выше имеет достаточно формальную структуру для реального текста комментария. Эта структура готова к размещению в файле XML. Здесь не будут представлены детали этого процесса (он рассмотрен в главе 3). Необходимо только сказать, что комментируя каждый метод в коде, можно автоматически получить законченную документацию, которая обновляется при изменении кода. Компилятор будет даже проверять, что документация соответствует сигнатурам методов и т.д.

Оглавление книги