Enhancing Code Quality with Documentation in C#

/// <summary>
/// This is a summary
/// </summary>

/// <summary>
/// Represents a mobile device.
/// </summary>
public class Mobile
{
    /// <summary>
    /// The total number of mobile devices created.
    /// </summary>
    private static int totalMobiles;

    /// <summary>
    /// The maximum battery level of the mobile device.
    /// </summary>
    private const int MaxBatteryLevel = 100;

    /// <summary>
    /// The _manufacturer of the mobile device.
    /// </summary>
    private string _manufacturer;
    /// <summary>
    /// Gets or sets the manufacturer of the mobile device.
    /// </summary>
    public string Manufacturer
    {
        get => _manufacturer; 
        set { _manufacturer = value; }
    }

    /// <summary>
    /// The _model name of the mobile device.
    /// </summary>
    private string _model;
    /// <summary>
    /// Gets or sets the model name of the mobile device.
    /// </summary>
    public string Model
    {
        get => _model; 
        set { _model = value; }
    }

    /// <summary>
    /// The current battery level of the mobile device.
    /// </summary>
    private int _batteryLevel;
    /// <summary>
    /// Gets or sets the battery level of the mobile device.
    /// </summary>
    public int BatteryLevel
    {
        get => _batteryLevel; 
        set { _batteryLevel = value; }
    }
}

/// <summary>
/// Gets the total number of mobile devices.
/// </summary>
/// <returns>The total number of mobile devices.</returns>
public static int GetTotalMobileCount()
{
    return totalMobiles;
}

/// <summary>
/// Initializes a new instance of the <see cref="Mobile"/> class with the specified _manufacturer and _model.
/// </summary>
/// <param name="manufacturer">The _manufacturer of the mobile device.</param>
/// <param name="model">The _model of the mobile device.</param>
public Mobile(string manufacturer, string model)
{
    this._manufacturer = manufacturer;
    this._model = model;
    totalMobiles++;
}

/// <summary>
/// Charges the mobile device by increasing the battery level.
/// </summary>
/// <param name="chargingPercentage">The percentage of mobile battery to charge.</param>
/// <exception cref="ArgumentOutOfRangeException">Thrown when the charging percentage is less than or equal to zero.</exception>
/// <exception cref="InvalidOperationException">Thrown when the battery level exceeds the maximum level.</exception>
public void ChargeMobile(int chargingPercentage)
{
   if (chargingPercentage <= 0)
   {
       throw new InvalidOperationException("Charging percentage must be greater than zero.");
   }

    _batteryLevel += chargingPercentage;

    // Ensure the battery level does not exceed the maximum level.
    if (_batteryLevel > MaxBatteryLevel)
    {
        throw new InvalidOperationException("Battery level has reached the maximum level.");
    }
}

Listing 4: Method ChargeMobile() with <exception> tags

<example>

This tag is used to demonstrate the practical usage of a method, showcasing different scenarios and showing developers how to effectively utilize this method.

/// <summary>
/// Resets the battery level of the mobile device to zero.
/// </summary>
/// <example>
/// <code>
/// Mobile iPhone13= new Mobile("Apple", "iPhone13");
/// iPhone13.ChargeMobile(88);
/// Console.WriteLine(iPhone13.BatteryLevel); // Output: 88
/// iPhone13.ResetBatteryLevel();
/// Console.WriteLine(iPhone13.BatteryLevel); // Output: 0
/// </code>
/// </example>
public void ResetBatteryLevel()
{
    _batteryLevel = 0;
}

Listing 5: Method ResetBatteryLevel() using <example> with <code> tag

<remarks>

This tag is used to provide additional comments or information that helps developers understand the code better. For example, it can explain validation rules or provide specific details about a property. In following listing 6, I've incorporated the remarks in the class Mobile and ResetBatteryLevel() method.

/// <summary>
...
/// </summary>
/// <remarks>
/// This class provides properties and methods to interact with a mobile device.
/// </remarks>
public class Mobile
{

    /// <summary>
    ...
    /// </summary>
    /// <remarks>
    /// This method should be used with caution as it will completely drain the battery of the mobile device.
    /// It is recommended to charge the device immediately after resetting the battery level to avoid complete shutdown.
    /// </remarks>
    public void ResetBatteryLevel()
    {
       _batteryLevel = 0;
    }    
}

Listing 6: class Mobile and method ResetBatteryLevel() with <remarks> tag

Before we explore the <seealso> tag, let's create a method named SendMessage() that combines all of the above tags, and then we can refer to this method using the <seealso> tag.

/// <summary>
/// Sends a message to the specified recipient.
/// </summary>
/// <param name="recipient">The recipient's phone number.</param>
/// <param name="message">The message to be sent.</param>
/// <returns>True if the message was sent successfully; else, false.</returns>
/// <exception cref="ArgumentNullException">Thrown when the recipient or message is null or empty.</exception>
/// <remarks>
/// This method uses the SMS service provider to send text messages.
/// </remarks>
/// <example>
/// <code>
/// Mobile iPhone14 = new Mobile("Apple", "iPhone14");
/// bool messageSent = iPhone14.SendMessage("1234567890", "sent from iphone");
/// if (messageSent)
/// {
///     Console.WriteLine("Message sent successfully.");
/// }
/// else
/// {
///    Console.WriteLine("Failed to send message.");
/// }
/// </code>
/// </example>
public bool SendMessage(string recipient, string message)
{
   bool isSent = false;
   if (string.IsNullOrEmpty(recipient))
   {
       throw new ArgumentNullException(nameof(recipient), "Recipient cannot be null or empty.");
   }

   if (string.IsNullOrEmpty(message))
   {
       throw new ArgumentNullException(nameof(message), "Message cannot be null or empty.");
   }

   // Magical code to send the text message and sets the value of isSent.
   return isSent;
}

Listing 6: Method SendMessage() with <summary>, <param>, <returns>, <exception>, <example>, <code> and <remarks> tags

<seealso>

This tag is used to provide references or links to other parts of the code, aiding in easier navigation for developers and allowing them to quickly access related code elements. It is important to note that the <seealso> tag should be written as <seealso cref=""/> to create a cross-reference to another code element.

/// <summary>
/// Sends an email to the specified recipient.
/// </summary>
/// <param name="recipient">The recipient's email address.</param>
/// <param name="subject">The subject of the email.</param>
/// <param name="body">The body content of the email.</param>
/// <seealso cref="SendMessage(string, string)"/>
public void SendEmail(string recipient, string subject, string body)
{
    // Magic code to send an email.
}

Listing 7: Method SendEmail() with <seealso> tag

IntelliSense

When you hover over a method call, you can view the complete summary description with proper sections. In the image below, you can see an example of me viewing the SendMessage() method. It displays the summary, returns, remarks, and exceptions tags information, providing a comprehensive overview of the method's purpose and behavior.

Figure 1: Summary tags information in tooltip

Conclusion

The summary tags in C# provide a powerful way to document your code and enhance its understandability. Clear and informative documentation helps developers understand your code faster, reduces errors, and promotes maintainability. By using these tags <summary>, <returns>, <param>, <exception>, <remarks>, <example>, and <seealso>, you can provide clear and concise documentation for classes, methods, properties, variables, and other code elements.

Remember to use the summary tags consistently throughout your codebase and keep your documentation up to date as your code evolves. Well-documented code not only benefits you but also contributes to the overall development team.