22. March 2013 09:22
Code commenting has given lesser priority most of time during programming. In actual, it needs similar or even more attention than code lines to give readability and maintainability 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 and hence code commenting is not an optional topic at all. In this article I am explaining some of the key points to be taken in to account while code commenting. My explanation is in the context of .NET programming and is somewhat similar for other languages also. Keep reading..
Self-Explanatory Variables and code lines
It is not necessary to write comments for every line of code and no need to write code for every variable you declared, but the variable name and the code line itself should be self-explanatory. By this way you can improve your code readability. Good, readable code requires very few lines of comments. Write comments only wherever required. If all variables and method names are meaningful, it will not need much commenting and that will make the code more readable.
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)
Method and constructor parameters need enough explanation so that the method usage will be seamless with proper intellisense.
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 make life difficult even for the owner of the code, after few days. So if there is complex logic blocks it is necessary to document it with proper comments so that code understandability should be their all time.
Special variable declarations
Any special declarations or anything of that sort need enough commenting to explain the usage.
It is a good idea to write the comment block before starting coding every section so that the purpose is clear before starting.