Commenting Code

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

If you follow the guidelines discussed in Using a Naming Convention and Structuring and Formatting Your Code, you are using a naming convention that identifies objects, variables, constants, and procedures, and you are using a prefix to indicate each variable's data type and scope. In addition to naming conventions, structured coding conventions, such as code commenting, can greatly improve code readability.

All procedures and functions should begin with a brief comment describing the functional characteristics of the procedure (what it does). This description, preceded by an apostrophe ('), should not describe the implementation details (how it does it), because these often change over time, resulting in unnecessary comment maintenance work, or worse yet, erroneous comments. The code itself and any necessary inline comments will describe the implementation. For example:

' This is a comment beginning at the left edge of the 
' screen.
Text1.Text = "Hi!"      ' Place friendly greeting in text 
                     ' box.

Note   Comments can follow a statement on the same line or can occupy an entire line. Both are illustrated in the preceding code.

See Also

Writing Solid Code | Writing Solid Script | Using a Naming Convention | Structuring and Formatting Your Code | Using Comments Effectively | Automating Code Commenting | Designing Code to Be Used Again