Code Documentation (Part 4)
Regions
Using
regions is a very good practice, whereas a region lets you specify a block of
code that you can expand or collapse. In longer code files, it is convenient to
be able to collapse or hide one or more regions so that you can focus on the
part of the file that you are currently working on.
Comments & XML Documentation
Comments
are a short descriptive lines, explaining what a line or more of code should do,
or might be addressing programmers about test code pieces or future changes.
Comments usually comes in two forms:
- In-line comments:
public bool
SendNotificationEmail(string toEmail,
string subject,
string body)
{
MailMessage message = new MailMessage();
message.To.Add(toEmail);
message.Subject = subject;
// This is the default from e-mail address, always use this address
message.From = new MailAddress("MyCodeLooks@Clean.now");
message.Body = body;
// SMTP e-mail relay for development, consider changing this when going
live
SmtpClient
smtp = new SmtpClient("YourSMTP");
smtp.Send(message);
}- XML Documentation: In Visual C# you can create documentation for your code by including XML elements in special comment fields (indicated by triple slashes) in the source code directly before the code block to which the comments refer.
/// <summary>
/// Send Notification E-mail
/// <para>Parameters: ToEmail | Subject | body </para>
/// <returns>Returns: bool (Boolean value indicates whether the e-mail was sent or not)</returns>
/// </summary>
/// <param name="toEmail">The Recipient E-mail Address</param>
/// <param name="subject">E-mail Subject</param>
/// <param name="body">E-mail Body Text</param>
public bool SendNotificationEmail(string
toEmail,
string subject,
string body)
{
// Send e-mail logic here
}
Documentation
will look like this when calling the method:
Here
are good tips to follow when using comments in your code:
- Use // or /// but never use /* … */
- Inline comments are usually used to describe details on one or more lines of code you’re implementing, however use inline comments wisely, in other words don’t over used them, describe what you are trying to do in less than three lines of comments.
- Use inline comments to explain assumptions, known issues and business rules.
- Don’t use inline comments to explain obvious code, too much comments will make the code unreadable.
- Unlike the above rule that applies for inline comments, use XML documentation comments generously, whereas this will save developers a lot of time taking the trip to the method definition to understand what the method does and what are the expected parameters to be passed.
- XML documentation can be used with code blocks definitions only, e.g. classes, interfaces, constructors, methods, etc… while inline comments can be used everywhere, however it’s highly recommended to use XML documentation comments on each code block definition and never use inline comments.
// Bad
Practice
// Get Employee Information by ID
public void GetEmployeeInformationById(int id)
{
// Do
some logic here
}
// Get
Employee Information by Social Security
public void GetEmployeeInformationBySocialSecurity(string socialSecurity)
{
// Do some
logic here
}
// Good Practice
/// <summary>
/// Send Notification E-mail
/// <para>Parameters: ToEmail | Subject | body </para>
/// <returns>Returns: bool (Boolean value indicates whether the e-mail was sent or not)</returns>
/// </summary>
/// <param name="toEmail">The Recipient E-mail Address</param>
/// <param name="subject">E-mail Subject</param>
/// <param name="body">E-mail Body Text</param>
public bool SendNotificationEmail(string
toEmail,
string subject,
string body)
{
MailMessage message = new MailMessage();
message.To.Add(toEmail);
message.Subject = subject;
message.From = new MailAddress("MyCodeLooks@Clean.now");
message.Body = body;
// SMTP e-mail relay for development, consider changing this when going live
SmtpClient
smtp = new SmtpClient("YourSMTP");
smtp.Send(message);
}
Comments
Post a Comment