Last post May 18, 2010 10:10 AM by atconway
May 18, 2010 09:35 AM|vivek_cs|LINK
What is the Microsoft Standard for Code Commenting
1. In case of Class 'Class header Comments
2. Function Comments
3. Subroutine Comments
There are different ways to comments like XML Documentation using ///
' Function: Page_Load
' Description: Prep the page for the user
''' Gets a list of matching a user
''' <param name="strDir"></param>
''' <param name="strUser"></param>
Which Stnd should follow? May be something else other than above?
May 18, 2010 10:10 AM|atconway|LINK
I don't know if there is a 'Microsoft' standard for code commenting. I am sure in Redmond within the development teams there are guidelines as to how they have to document their code, but I am not sure if that has produced any official MSDN documentation
on 'Comment like this according to MSFT...'.
I find that commenting and how code is commented is something that stems from the more seasoned developers in the environment you work in. Typically this is a Senior person with years of experience and coding that might use their experience to formulate
guidelines for commenting code. I think the bottom line is that code documentaion
must be done at least to a minimum to avoid looking at code in the future and not having a clue what it does (maybe not that extreme, but it is worse for complex algorithms or business logic).
Personally I like a combination of custom method header in conjunction with the built in XML documentation (3 tics ''' note XML Documentation must be checked in the 'Compile' tab of project properties for this to work) in VS.NET. One of the nest parts
of the XML documentation is the ability to take the .XML file from the bin to look at the documentation separately without having to open the code. As for how you apply the commenting, headers for methods, classes, properties, etc I say 'Yes' to all.
Take a look at this MSDN article which does have a good bit of detail in regards to the built in XML commenting in VS.NET:
XML Comments Let You Build Documentation Directly From Your Visual Studio .NET Source Files:
Hope this helps!