Preprocessor Directives & .NET XML Documentation
.NET framework has everything what it takes to develop a highly customizable software application. Apart from providing thousands of built in classes in language library and common language runtime, .NET offers variety of options during code compilation. Using visual studio you can access those options via user interface. However, there are certain compilation features that need to be integrated in code. This is where preprocessor directives play important role. In this article we are going to throw light upon preprocessor directives. In addition to preprocessor directives, another important feature that allows proper documentation of C# code is that of XML documentation. XML is the medium of transferring information over the internet. Therefore, it is always a good practice to document your C# code in XML. We will show how to do this in this article. But before that, let us start our discussion with preprocessor directives.
Preprocessor directives in simplest words are the directives which affect the output behavior of the compiled code. These directives actually tell the compiler at run time about the regions of the code and how should they be compiled. Unlike C and C++, C# doesn’t contain any separate preprocessors which can be employed to create macros from directives. Preprocessor directives are supported by .NET framework 1.1 and above.
Preprocessor directives are simple to define. Preprocessor directives start with a hash sign ‘#’ followed by the name of the directive. Preprocessor directives can be used to perform variety of operations few of which are as follows.
Preprocess directives allows us to set conditions during code compilation. We can tell the compiler that exclude or include following lines of code while you are compiling the code. The conditional preprocessor directives available in C# are #if, #else, #elif, #define, #undefine, #endif.
Errors & Warnings
Following preprocessors are used for signaling warnings and errors.
In order to more effectively organize your code, you can give a name to a certain block of your source code. You can collapse and expand that piece of code via region preprocessors. There are two preprocessors used for this purpose: #region and #endregion.
Now when we have theoretically explained the concept of preprocessor directives, let us put this concept into practice. Have a look at Example1 to further grasp the concept of preprocessor directive.
Now let us come back to our code in Example1, we have defined a preprocessor directive #define DEBUG. Now, we if we pass the DEBUG expression to conditional preprocessor directive, it will evaluate to true and the statements within the ‘if’ conditions will execute. Now come inside the main method, here we have put a conditional preprocessor directive and which tells the compiler that if the code is being compiled in DEBUG mode and DEBUG directive has been defined in the application, then include these statements in the compiled code, otherwise ignore these statements. The compiler will check that #define DEBUG has been defined at the top of the code therefore it will execute that piece of code. The statement after the preprocessor directive #else would not execute because we have DEBUG directive at the top of our file. The output of our code will be as follows.
Or '||', and '&&' and not '!' operators can also be used along with conditional preprocessor directives. This concept will be elaborated with the help of another example. Have a look at the code in Example2.
Importance of documenting code is enormous. Documentation helps stakeholder, particularly developers to share information about the modules, blocks, types and members of code. Documentation is basically set of information, in the form of comment that describes a particular type, member, module or any piece of code in your application.
There are two way to add comments to your application. One is the traditional way to add comments where you simply put a double slash ‘//’ and write a single line comment against any piece of code or you use /* some comment …… */ to write double line comments. These comments are good for documenting short information that can be read while modifying the code. However, to automatically generate documentation from code and to build an XML documentation file for code, you need to document your code using XML documentation syntax which we will explain in this section.
An XML single line comment begins with a triple slash, followed by some tags. For example,
Have a look at Example3. Create a Visual Studio 2010 console application and place this code in a separate file. Or you can also place this code in the same file where the class containing the main method is located.
Now, you must be wondering what the advantages of XML documentation are. To see the advantage that XML documentation brings with it, add the following class in the same namespace in which you created the car class or you can add this class in the same file as of Car class’s file. This class contains the main method and would show you a glimpse of the power of XML documentation
Similarly, when you declare an object of Car class, when you type the new followed by the type name, Visual Studio will use its IntelliSense feature to display the summary of the constructor that we commented in part1 of Example1. Also the detail of the parameter that we have to pass is available as shown in the following figure where the detail of the parameter ‘name’ is given. This detail is the same as we commented in XML documentation’s param tag, before defining the constructor which is as follows.
The first advantage of XML documentation is the IntelliSense feature which gets activated on the types for which you write XML documentation. Another great advantage of XML documentation is that you can automatically generate a documentation file that contains all the XML comments of the application. This file can be used to generate HTML based documentation for your application that can be used over the internet.
In order to generate an XML documentation file for the application, you need to follow these steps.
|All times are GMT +5.5. The time now is 15:46.|