16 Comments

16.1 General Good Practices for Commenting in Programming with VBA Examples

Prioritize Clear Code Over Comments:
- Explanation: Write code that is clear and self-explanatory. If the code itself can be made clearer through better naming or structure, prioritize that over adding a comment to explain unclear code.
- Bad Practice Example:
```
' Increment the counter by 1
i = i + 1
```
  - Why It’s Bad: The comment merely restates what the code is doing without adding any new information. Instead, the variable i could have a more descriptive name, like counter, to make the code self-explanatory.
Use Comments Sparingly:
- Explanation: Comments should be used only when they add value. Avoid adding comments that describe what the code does in a way that is redundant or unnecessary.
- Bad Practice Example:
```
' This line of code sets the value of cell A1 to 5
Range("A1").Value = 5
```
  - Why It’s Bad: The comment simply restates the obvious. The code itself is straightforward, and the comment doesn’t provide any additional insight.
Avoid Redundant and Misleading Comments:
- Explanation: Comments that restate the code or provide incorrect information can be confusing and should be avoided.
- Bad Practice Example:
```
' Subtracting 1 from the total
total = total + 1
```
  - Why It’s Bad: The comment incorrectly describes the action performed by the code, which actually adds 1 to total. Misleading comments like this can lead to errors in understanding and maintaining the code.
Keep Comments Updated:
- Explanation: As code evolves, comments need to be updated to reflect the current state of the code. Outdated comments can mislead developers.
- Bad Practice Example:
```
' This code checks if the number is greater than 10
If number < 5 Then
    MsgBox "Number is less than 5"
End If
```
  - Why It’s Bad: The comment describes an old version of the code. The code now checks if the number is less than 5, not greater than 10. Failing to update the comment leads to confusion.
Use Comments for Intent and Rationale:
- Explanation: Comments should explain why certain decisions were made, especially if they are not immediately obvious from the code itself.
- Bad Practice Example:
```
' Special calculation
result = x * y + z
```
  - Why It’s Bad: The comment does not explain the reason behind the calculation or why it’s “special.” Without context, future developers won’t understand the rationale behind the formula.
Legal and Informative Comments:
- Explanation: Include necessary legal or informative comments, such as copyright notices or explanations of non-obvious code, when required.
- Bad Practice Example:
```
' Returns true if the value is found
Function SearchValue()
    ' Code here
End Function
```
  - Why It’s Bad: The comment is vague and doesn’t explain what the function actually does, what value it’s searching for, or what “found” means. The function name itself is also too generic.
Avoid Commenting Out Code:
- Explanation: Instead of commenting out code, consider removing it if it’s no longer needed. Commented-out code can clutter your codebase and cause confusion.
- Bad Practice Example:
```
'Old approach
'Range("B1").Value = 10
```
  - Why It’s Bad: This commented-out code adds clutter and can confuse future developers. If the old approach is no longer needed, it should be removed.
Minimize Noise Comments:
- Explanation: Avoid comments that add no value, such as those stating the obvious or repeating what the code already clearly conveys.
- Bad Practice Example:
```
' Declare an integer variable
Dim counter As Integer
```
  - Why It’s Bad: The comment is unnecessary because the code is self-explanatory. It adds noise without providing any useful information.
Consider the Longevity of Comments:
- Explanation: Write comments that will remain relevant and useful over time. Ensure that they provide long-term value and aren’t likely to become outdated.
- Bad Practice Example:
```
' Temporary fix for bug
Range("A1").Value = "Fix"
```
  - Why It’s Bad: The comment labels the code as a “temporary fix,” but without a plan to revisit and update the code, it could remain indefinitely, leading to potential issues down the line.
Use Descriptive Naming Over Comments:
- Explanation: Whenever possible, use descriptive names for variables, functions, and procedures to make the code self-documenting, reducing the need for comments.
- Bad Practice Example:
```
' Check if x is less than y
If x < y Then
    MsgBox "x is less than y"
End If
```
  - Why It’s Bad: Instead of relying on the comment, renaming x and y to something more descriptive, like currentValue and threshold, would make the code clearer without needing a comment.