locked
Microsoft Vb.NET Code Comment Structure RRS feed

 > 

  • Question

  • Question
    Sign in to vote
    0
    Sign in to vote
    User-266166614 posted

     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
    ' ===================================================

    ''' <summary>
    ''' Gets a list of matching a user
    ''' </summary>
    ''' <param name="strDir"></param>
    ''' <param name="strUser"></param>
    ''' <returns></returns>
    ''' <remarks></remarks>

    Which Stnd should follow? May be something else other than above?

     

    Tuesday, May 18, 2010 9:35 AM

Answers

  • Question
    Sign in to vote
    0
    Sign in to vote
    User-952121411 posted

    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:

    http://msdn.microsoft.com/en-us/magazine/cc302121.aspx

    Hope this helps! Smile

     

    • Marked as answer by Anonymous Thursday, October 7, 2021 12:00 AM
    Tuesday, May 18, 2010 10:10 AM