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;
            // 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);
        }

Comments

Post a Comment

Popular posts from this blog

Machine Learning Explained!

Image
The minute we hear the word machine learning, many thoughts rush into our minds, starting from high-tech robotics, sophisticated complex algorithms and ending by Sci-fi movies (of course!). Well, we might be partially right if the plan is to assemble a robot or reinvent an auto-pilot car, but this is no longer the case these days! In the recent years, Machine Learning is being widely used in business scenarios or – to be fair – it’s even becoming mainstream! Predictive machine learning modules and/or sentiments are being used in our day-to-day tools and utilities. For example, there are off-the-shelf SaaS sentiments to tell whether a tweet from a customer is a good feedback (happy customer) or a bad feedback (unhappy customer). Another example that we could find off-the-shelf is face recognition, which is a service we could feed with a couple of (face) photos of a person, and then feed a totally different photo – of the same person – other than the ones provided at the begin...
Read more

Building JSON Objects in Microsoft Flow

Image
A couple of days ago, I was helping a friend with a case in Microsoft Flow ... So I thought this is a good time to write a new article that would be a reference for my friend, and hopefully others would find this useful if they came across the same issue. The Case It's very simple and straight forward, we have a flow that gets initiated once an item is added to a SharePoint list, and we want to return a JSON object of the newly added item ... Easy! Good to know... Now before going into the solution, it's good to know that Microsoft Flow itself handles data within as JSON, whereas Flow is not only a process automation service, it's an integration service as well. Therefore it needs a common ground/language/format - you name it - to handle all data types from all the different sources (SharePoint list, SQL Table, Excel, etc...) This is How... Well, there are two different ways to tackle the case above, and I'm going to list them both in this article....
Read more

Microsoft Flow as a Service for Custom Applications

Image
I've been so eager to write about Microsoft Flow since I have started using it about a year ago! However, I've seen a lot of articles out there by community contributors talking about almost every single capability that Flow can do ... In addition, I personally believe that the Microsoft Flow team is doing a good job putting people on the right learning track. There are many scenarios that we could consider using Flow with, however in this very post I'll be writing about when to consider Flow while building custom developed applications ... Flow could be your "LEGO"  building block for almost every application! As developers, almost every single one of us have developed against at least one API, and I surely believe that many have developed APIs that connects to third party services and/or social media ... Now, this task is usually a bit costly during the project, whereas developers have to go through the technical documentation for those APIs and absorb th...
Read more