Dotnet Stuff

What is the relevance of Code commenting? Is code commenting a waste of time or productivity killer?

In this article, we point out the Importance of Code Commenting and Code Commenting Best Practices in C#.

Code commenting has given lesser priority by the programmer most of the time. At times it is completely avoided and after review comments were added on demand.

In actual, Code commenting needs similar or more attention to having better readability and maintainability of the source code in the long run.

It is quite common that code written by one programmer will be maintained or upgraded by various other developers during the product life span.Hence code commenting is not an optional topic at all.Every programmer should know the art of commenting code.

Code Commenting Best Practices in C# /.NET Languages.

In this article, I am explaining some of the key points to be taken into account while code commenting in C# or programming languages in common.

My explanation is in the context of .NET programming and that is somewhat similar to other languages also.Keep reading the code commenting best practices C#.

1. Avoid Incorrect Commenting

Incorrect comment is worse than no comment.

Write only correct and clear comments.it is better to not write comments that are incorrect or wrong in explanation.

2. Avoid Over-Commenting

Write required comments only.Comments should be short and clear. Avoid commenting on self-explanatory statements.

3. Self-Explanatory Variables and Code Blocks

It is not necessary to write comments for every line of code and no need to write explanation for every variable you declared, but the variable name and the statement lines should be self-explanatory to understand.

This can improve your code readability. Good, readable code requires very few lines of comments. Write only specific comments wherever required.

If all variables and method names are meaningful, there is no need of much commenting and hence the code will be clean and more readable.

4. XML Commenting

Proper XML commenting( /// commenting) is mandatory for all public and internal methods so that proper method/property IntelliSense will be available during usage.(See Visual Studio Method/Property IntelliSense as samples and follow similar commenting style)

5. Parameter Explanation

Parameters of functions and constructor need to have enough explanation so that its usage will be easier with proper understandable IntelliSense.

6. Enough comment for complex Logics

Lesser lines of comments will make the code more elegant. However, most of the time it compromises the code understanding and makes life difficult even for the owner of the code, after few days.

So if there are complex logic blocks then it is mandatory to document it with proper comments so that code understandability should be there all the time.

7. Special Variable Declarations | Constants Definitions

Any special declarations or anything of that sort needs enough commenting to explain the relevance.

It is always a good idea to write the respective comment before coding the functionality so that the purpose and detail of the code block functionality are made clear well before beginning the code.

Summary

This post covered the best code commenting practices to follow in C#.NET. Hope you find this tips helpful.Follow dotnetstuffs.com for more useful stuff.Don’t forget to leave your feedback in the comment section below.