Comments and Documentation

# CHAPTER 5

Comments and Documentation #

1. Introduction #

2. Learning Objectives #

• Understand why comments are considered an apology for bad code.

• Identify and delete Redundant, Noise, and Misleading comments.

• Refactor messy code to eliminate the need for explanatory comments.

• Write "Good Comments" (Legal, Warning, Amplification).

• Utilize standardized documentation blocks (PHPDoc / JSDoc) effectively.

3. The Problem with Comments (They Lie) #

• The Scenario: A developer writes a complex function and adds a comment explaining it. Six months later, another developer alters the function logic to fix a bug, but *forgets to update the comment*.

• The Result: The comment is now a lie. The next developer who reads the file will trust the comment, misunderstand the code, and introduce a massive bug. The only thing worse than no comment is an inaccurate comment.

4. Bad Comments (What to Avoid) #

• Redundant Comments: Explaining what the code obviously does.

• *Bad:* // Check if user is active followed by if ($user->isActive()). The comment adds zero value.

• Noise Comments: Auto-generated garbage by IDEs.

• *Bad:* / @param string $name The name */

• Commented-Out Code: The worst offender. Developers comment out 50 lines of old code "just in case we need it later." It rots in the file forever. Delete it! That is what Git (Version Control) is for. If you need it later, look at the Git history.

• Journal Comments:** // Added by John on Oct 12. Use Git blame, not comments.

5. Explaining Yourself in Code #

// Check to see if the employee is eligible for full benefits
if (($employee->flags & HOURLY_FLAG) && ($employee->age > 65)) { ... }

*After (Expressing in code):*

if ($employee->isEligibleForFullBenefits()) { ... }

*(The comment was deleted because the new method name tells the reader exactly what is happening).*

6. Good Comments (When they are justified) #

• Legal/Copyright Comments: Standard corporate licenses at the top of a file.

• Warning of Consequences: // WARNING: Executing this function will take 5 minutes and lock the database.

• Explanation of Intent (The "Why"): Code tells you *How*. Sometimes you need a comment to explain *Why* you did something weird.

• *Good:* // We use a bubble sort here instead of quicksort because the legacy hardware API crashes if memory exceeds 2MB.

• Amplification: Highlighting the importance of something that looks unreasonable.

7. Documentation Blocks (PHPDoc / JSDoc) #

• Purpose: PHPDoc/JSDoc blocks are parsed by IDEs to provide autocomplete, type hinting, and auto-generated HTML documentation.

• Rule: Only use them for public interfaces. Do not clutter private, internal helper functions with massive DocBlocks that restate the obvious.

8. Diagrams/Visual Suggestions #

/**
 * Calculates the total tax for an invoice based on regional laws.
 * 
 * @param float $subtotal The total before tax (Must be > 0)
 * @param string $regionCode The 2-letter ISO state code
 * @return float The calculated tax amount
 * @throws InvalidRegionException If the region code is not supported
 */
public function calculateRegionalTax(float $subtotal, string $regionCode): float { ... }

9. Best Practices #

• The Delete Key is your Friend: During a code review, if you see a block of code with a comment explaining what it does, challenge the author to extract that block into a well-named function and delete the comment.

10. Common Mistakes #

• Mandatory Comments: Some toxic corporate environments enforce a rule: "Every function must have a comment." This leads to developers writing mindless, redundant garbage just to pass the code review. Comments should be a rare exception, not a mandatory rule.

11. Practice Exercises #

1. 1. Find a piece of "Commented-out code" in a project. Explain why leaving it there is detrimental to the codebase, and what tool should be used instead to recover old code.

1. 2. Give an example of a "Why" comment (Explanation of Intent) that justifies its existence in a codebase.

12. MCQs with Answers #

13. Interview Questions #

• Q: A junior developer submits a Pull Request where every single variable assignment has a comment explaining what it is doing (e.g., // Add 1 to the count). How do you address this in your code review?

• Q: Explain the concept of "Self-Documenting Code." How does refactoring a complex if statement into a named method eliminate the need for an explanatory comment?

• Q: What is the difference between writing comments to explain the "How" versus writing comments to explain the "Why"? Which one is acceptable in Clean Code?

14. FAQs #

15. Summary #

16. Next Chapter Recommendation #