Developing software is just one part of the job, writing code. Also, it is equally important that code is well written and easy to understand, as well as adequately documented. Maintaining clean structure in the codes; and making sure that these programs are easily updated is greatly facilitated by documentation and code commenting which form an integral part of software development.

We will explore code commenting, clean code and dotnet core documentation generation. We will talk about why these things are essential, how they can be implemented as well as provide examples or snippets of codes that illustrate their use.

Code Commenting
It involves including text within a code file in order to explain what the code does. This may be used to explain the purpose behind a certain function or method or provide additional information about it. Code commenting plays an important role in programming because it ensures that the code remains maintainable and understandable over time.

There exist different types of comments for codes; single line comments as well as multi-line comments. Single-line comments come in handy when explaining one line of code while multi-line ones serve when explaining several lines of codes.

Here is an example of a C# single-line comment:

// This is a comment that explains what this line of code does


int age = 25;

This is how write a C# multi-line comment :
/*
This is a comment that explains the purpose of this block of code.
It can span multiple lines and is useful for providing detailed
explanations about the code.
*/
int[] numbers = { 1, 2, 3, 4, 5 };

While commenting on your codes; ensure clarity and brevity. Comments should serve to explain the program’s code but not too much information that they become distracting or hard to read.

Clean Code
It is important to understand that clean code means code, which can be easily understood by others and follows unified coding style. Writing clean code has several its importance. First and foremost, it makes the maintenance process of the code simpler for future use. Furthermore, it helps others read and comprehend codes better in cases where programming involves teamwork or sharing with others. Finally, clean codes are usually more efficient and have fewer mistakes in them.

Some tips on how to write clean code include:

  1. Use names that are meaningful and descriptive for your variables and functions

  2. Break complex logic into smaller manageable parts.
  3. Keep functions and methods short and focused on a single task.
  4. Use consistent indentation and spacing to make the code easier to read.
  5. Comments can be used to explain why some decisions were made

Following these guidelines will enable you to author squeaky-clean, maintainable, understandable codes.

.NET Core Documentation Generation

.NET Core is a modern application development platform that works across platforms as open source among other tools therein aimed at facilitating generation of documents’ arrangements of user’s codes.

Among the .NET Core most useful features are XML documentation comments, which are special types of comments starting with three forward slashes (///) intended for providing documentation for classes, methods, and properties.

C# XML Documentation Comment Example:
/// <summary>
/// Gets the current date and time.
/// </summary>
/// <returns>The current date and time.</returns>
public DateTime GetCurrentDateTime()
{
    return DateTime.Now;
}

Moreover, the tag <summary> is utilized in providing a summary about what the method does, while tag <returns> for describing the value returned by this method.

To generate documentation out of XML documentation comments use dotnet build command with /doc.

Recent Posts