Original
Using annotations in CSharp
Note: This article is happy on the good original, and once published in the "Windows World", not welcome to paste, Thank!!!
Because of the complexity and unpredictability of the software, it's a good idea to add annotations to your program, especially in team development, to make your programs more readable.
We know that csharp (i.e. C #) is an extended version of the C + + language, inheriting the annotation method of C + +, that is, the annotation method of "//" for one line, or the annotation method that spans lines "/*/*". Can be easily used by all developers.
Example One：
/*
Author: Just be happy.
version:1.0
Date:: 2001/6/19
Description: Building a Test class
*/
public class test{
This class has only one public method
public static void Main () {
System.Console.WriteLine ("Hello,world");//output Hello,world statement;
}
}
Description:In this simple program, we use two simple annotation methods, first of all, we know that the "/**/" method is suitable for cross row annotations. Generally speaking, we use this method to make a simple description of the whole file in the header of a program body.
The//Start Comment statement has a valid range from the symbol to the end of the line, and the//symbol can either be placed at the beginning of the row or anywhere in the line.
At the same time, we should note that, if possible, do not use nested annotation statements, although some compilers can automatically process these nested annotation statements, but as a good programmer, in their programming should develop a good habit, try to avoid this situation.
Case Two:
/*
Author: Just be happy.
version:1.1
Date:2001/6/19
Description: A reasonable extension of the test class
*/
public class test{
public static void Main () {
/*
This is a nested annotation and is an unreasonable state
*/
System.Console.WriteLine ("Hello,world");
}
Through the above two sets of examples, we now have a basic understanding of the annotations, but if these are the only statements that may not be worth such a lengthy presentation, we now begin to introduce a dedicated annotation method in CSharp-"///"-and give a detailed description of this annotation method.
The annotation method referenced by CSharp, in principle, is compatible with the original "//" and is also a single-line annotation method, but it is more powerful because it adds some annotation statements and integrates the corresponding vs.net.
Example Three:
/*
Author: Just be happy.
version:1.2
Date:2001/6/18
Description: Building a Test class
*/
<Summary> a test class </Summary>
public class test{
<Summary> Entry Method </Summary>
public static void Mial () {
System.Console.WriteLine ("Hello,world");
｝
}
We can look at the different aspects of the previous annotation. First we noticed that we added a <Summary> identifier. But here we may not have realized what it is useful for, on the contrary, for some handwritten code friends, we may also feel that this writing may add some burden, because we have to typing a few more words.
Wait a minute, here we begin to compile the program, we know, CSharp's compiler command for CSC, if you have a careful study of this command, we can see that it has a parameter for/doc, then what is the use of this parameter?
Below, we save the file in example three as C:\test.cs and compile it using the following command line:
Csc/t:exe/doc:test.xml Test.cs
Let's take a look at the C-packing directory, there will be a new XML file, that is, Test.xml, using a browser to open, its file contents are:
<?xml version= "1.0"?>
-<doc>
-<assembly>
<name>
Test</name>
</assembly>
-<members>
-<member name= "
t:test">
<Summary>
a test class</Summary>
</member>
-<member name= "
M:test. Main">
<Summary>
Entry Method</Summary>
</member>
</members>
</doc>
So far, we may still not have seen what this thing is useful for. It just produces an XML file.
If you have a Java programmer in this room, you may be dismissive, because in the Java Compilation tool, you provide Javadoc files, organize annotations in Java programs, and generate a readable HTML file that can be used as a description manual for a class.
In fact, the doc parameter of CSC also plays a similar role, but it only generates an intermediate XML data file. With the powerful features provided by vs.net, this XML data file forms a powerful description file, and even in team development, you can automatically produce a detailed design document by writing it clearly, without having to write a document yourself after you have finished writing the program.
In the CSC comment statement, in addition to the <Summary> identifier, Microsoft also provides other identifiers, the following we introduce each:
identifiers
description and examples
applied to
<Summary>
A summary description of the whole
<summary>Description</summary>
classes, attributes (not recommended), methods, and so on
<para>
Following the summary, an effective explanation is made of the entry parameters involved in the method.
<param name=username> This parameter is the user's account number </param>
The entry parameters of the method;
<returns>
The return value of the method is interpreted;
<returns> return value 0 represents successful operation,-1 represents unsuccessful Operation </returns>
The return value of the method;
<remarks>
Descriptive remarks about some statements
<remarks> This class needs to invoke another user class related method </remarks>
Classes, methods, attributes, etc.;
<see>
Produces a hyperlink in the generated document that is connected to another description;
<see cref= "[member]"/>
Can be added in other annotation identifiers
<seealso>
The difference with the above is that this identifier shows the "See Also" area of the hyperlink at the end of a document, while the former is in the document;
<seealso cref= "[member]"/>
cannot be added to other annotation identifiers
<value>
A summary explanation of a property;
<value> This is a public property </value>
Property
<code>
If you need to place part of the source code snippet, you can use this identifier to mark it out
<code>
public int Add (int a,b)
{return a+b;
}
</code>
Can be added in other annotation identifiers
<exception>
Explain the exceptions that may be thrown in the program;
<exception cref= "System.Exception" > Thrown exception </exception>
This identifier can be used to interpret the method if there is an exception thrown, such as "Try...catch structure"
<permission>
Make some explanations for the access rights of the method:
<permission cref= "System.Security.PermissionSet" > This is a public method </permission>
Methods, properties
<c>
Basically the same as the <code> identifier, but this identifier is used only for a single line of code;
<c>return a+b;</c>
can be inserted in other identifiers;
<example>
Examples, usually with <code> supporting use;
<example> The following example shows how to call the Add method:
<code>
Class MyClass
{
public static int Main ()
{
Return Add (1+2);
}
}
</code>
</example>
can be inserted in other identifiers;
<paramref>
Refer to an entry parameter elsewhere
<paramref cref= "A" > Please note that this is an integer parameter </paramref>
Note:
The methods in this table can also be called member functions (this is VC + +
the usual name);
In addition, about <list>
identifier We don't have an explanation here, interested friends can read the SDK
or other related materials;
Having explained these things, we now give a detailed example to all of you, and now let's look at the various conveniences that these identifiers bring to us (here, I assume you have Visual Studio.NET in your hands)
Example four:
Using System;
<summary>
Classname:someclass
version:1.0
Date:2001/6/21
Author: Just be happy.
</summary>
<remarks>
This class is only a sample teaching class and does not complete the specific work
</remarks>
public class SomeClass
{
<summary>
Internal private variable, storage name </summary>
private string myname = null;
Public SomeClass ()
{
//
Todo:add Constructor Logic here
//
}
<summary>
Name Properties </summary>
<value>
This property is read-only and returns the user name </value>
public string Name
{
Get
{
if (myname = null)
{
throw new Exception ("Name is null");
}
return myname;
}
}
<summary>
This method is not specifically constructed </summary>
<param name= "s" > entry parameter S is a string type </param>
<seealso cref= "String" >
String type of information </seealso>
public void SomeMethod (string s)
{
}
<summary>
The method is still not specifically constructed </summary>
<returns>
The return value is always 0.</returns>
<seealso cref= "SomeMethod (String)" >
See the description of the SomeMethod (string) method </seealso>
public int Someothermethod ()
{
return 0;
}
<summary>
The entry for the application
</summary>
<param name= "args" > entry parameter Set </param>
public static int Main (string[] args)
{
//
Todo:add code to start application
//
return 0;
}
}
Below, we copy this program in Visual Studio.NET and select "Build Comment Web Pages ..." In the Tools menu, and a dialog will pop up, and after we click OK, we can see that the system is sorting through the notes. Finally, a Web document will appear.
This web document, we can open using HTML, please look at the following figure
Is it better than the annotations produced by Javadoc? All comments are sorted by Visual Studio.NET and can be made visible to other people on the same team:
But this annotation is not just to produce this annotation document, but more importantly, it can provide the role of intelligent hints in programming.
Still, for example, I use a new file, and in this file I refer to some of the properties and methods defined in example four, as shown in the following illustration:
As we can see clearly from the diagram, Visual Studio.NET automatically adds the original annotations to the smart tip.
We can imagine that if you are involved in development in a team, and when other people on the team need to call you on a piece of the program, he can even not open your source code, you can take advantage of visual Studio.NET provides powerful functionality to traverse all the attributes and methods in your class file, and to get descriptions of these properties and methods based on the comments you write!
To sum up, Microsoft in visual The newly added annotation method in the Studio.NET, provides a more convenient means for team development to strengthen the relationship between team members, while individual programmers also get more benefits, so in writing your own program, we'd better knock a few more words, to their own program to add this format annotation!
