Test Design StudioGo to Previous Topic: CA0203 - Document public methods and propertiesGo to Next Topic: CA0205 - Document public constants

CA0204 - Document private methods and properties

Summary

The ability to create routines (i.e. Function and Sub) is attributed as one of the most powerful features of software development. When a developer decides to call a routine, they need to have a clear understanding of what that routine does and the expectation of arguments passed to that routine.

Note:    This rule applies to items of Private scope. See rule CA0203 for items of Public scope.

Solution

For 'Sub' declarations, include XML Comments with at least the 'summary' tag. If your routine takes parameters, each parameter must be documented with the corresponding 'param' tag and at least the 'type' attribute.

[VBScript] - Copy Code
''' <summary>Document the sub here</summary>
''' <param name="myParameter" type="String">Optional parameter details here</param>
Private Sub HelloWorld(ByVal myParameter)
End Sub

For 'Function' declarations, include XML Comments with at least the 'summary' tag and the 'returns' tag. The 'returns' tag should include the 'type' attribute to indicate the type of value returned from the function. If your function takes parameters, each parameter must be documented with the corresponding 'param' tag and at least the 'type' attribute.

[VBScript] - Copy Code
''' <summary>Document the function here</summary>
''' <param name="myParameter" type="String">Optional parameter details here</param>
''' <returns type="String">Optional comment about the return value here</returns>
Private Function HelloWorld(ByVal myParameter)
    HelloWorld = "Hello World"
End Function

For 'Property' declarations, the XML Comments vary depending on if the property is the 'Get', 'Let', or 'Set' declaration. The 'Get' declaration is the only one that needs to at least have the 'summary' tag and the 'value' tag. The 'value' tag should include the 'type' attribute to indicate the type of value returned from the property. If any of your property declarations take parameters (Let, Get, or Set), each parameter must be documented with the corresponding 'param' tag and at least the 'type' attribute.

[VBScript] - Copy Code
Class MyClass

    ''' <summary>Document the property here</summary>
    ''' <value type="String">Optional comment about the value here</value>
    Private Property Get Value()
    End Property

    ''' <param name="data" type="String">Optional parameter details here</param>
    Private Property Let Value(ByVal data)
    End Property

    ''' <param name="data" type="RegExp">Optional parameter details here</param>
    Private Property Set Value(ByRef data)
    End Property

End Class