Commenting
Commenting is the practice of inserting human readable messages into your code, purely for annotation, description, and to make things clearer to the reader. In C#, one-line comments are prefixed with the // symbol, and multiline comments begin with /* and end with */. Comments are used throughout the code samples in this book. Comments are important, and I recommend that you get into the habit of using them if you're not already in the habit. They benefit not only other developers in your team (if you work with others), but you too! They help remind you of what your code is doing when you return to it weeks or months later, and they even help you get clear and straight about the code you're writing right now. Of course, all these benefits depend on you writing concise and meaningful comments and not long essays filled with irrelevance. However, MonoDevelop offers XML-based comments too to describe functions and arguments specifically and which integrates with code completion. It can significantly boost your workflow, especially when working in teams. Let's see how to use this. Start by writing your function or any function, as shown in the following screenshot:
Writing a function (AddNumbers) in MonoDevelop (preparing for code commenting)
Then insert three forward-slash characters on the line above the function title (///), as shown in the following screenshot:
Inserting /// above the function title to create an XML comment
When you do this, MonoDevelop automatically inserts a template XML comment ready for you to complete with appropriate descriptions. It creates a summary section that describes the function generally and param entries for each argument in the function, as shown in the following screenshot:
Inserting /// above the function title will autogenerate an XML comment
Next, fill in the XML template completely with comments for your function. Be sure to give each parameter an appropriate comment too, as shown in the following screenshot:
Commenting your functions using XML comments
Now, when calling the AddNumbers function elsewhere in code, the code-completion pop-up helper will display both the summary comment for the function as well as the parameter comments' context sensitively, as shown here:
Viewing comments when making function calls
