Способы документирования кода на c#

Автор: Topol Пятница, Июнь 8th, 2012 Нет комментариев

Рубрика: Программирование

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

Более популярна однострочная версия. Многострочная фактически не поддерживалась, пока не появился компилятор версии 1.1. Стоит отметить, что спецификация языка версии 1.0 определяла многострочную версию. Синтаксический признак однострочной версии в Visual Studio – это наличие тройного слэша в начале строки.

Для вставки перед функцией либо классом комментария, нужно набрать на клавиатуре ‘///’. Затем вставится стандартный комментарий. В случае с функцией данный комментарий описывает не только общую информацию, но также параметры и результат. На строке, которая предшествует оператора, ставится комментарий операторов. Таким образом, в случае надобности удобно дописать или исправить код. Выполнение правил документирования функций и классов позволит делать документацию на код с помощью автоматических средств Visual Studio.

Документирование кода на С# возможно с использованием XML документации, или документирующих комментариев XML. Так называются специальные теги XML. Они содержатся в комментариях, описывают методы и свойства в конкретном файле. Необходимо всегда заполнять XML комментарии.

Благодаря такому подходу, комментарии в проекте стандартизируются. Кроме этого, IntelliSense в автоматическом режиме будет отображать информацию о документированных параметрах и методах, в т.ч. встроенных во фреймворк. Облегчится работа и экономится время автора и других разработчиков. Есть возможность на этапе компиляции сгенерировать XML файл, содержащий все данные.

Для создания документации для кода в Visual Studio C# в специальные поля для комментария включаются теги XML. Компилятор, выполняя компиляцию с параметром /doc, найдет в исходном коде все теги XML для создания файла документации XML. Чтобы на основе файла, собранного компилятором, создать конечную документацию, можно применить Sandcastle.

Помните, комментарии XML-документации – это не метаданные, они не входят в скомпилированную сборку, к ним невозможно обратиться с помощью отражения.

Источник: cisharp.com

Оставить комментарий

Чтобы оставлять комментарии Вы должны быть авторизованы.

Похожие посты