Formatting and Code Structure

# CHAPTER 6

Formatting and Code Structure #

1. Introduction #

2. Learning Objectives #

• Understand formatting as a tool for visual communication.

• Apply the "Newspaper Metaphor" to class and file structure.

• Utilize vertical spacing to separate distinct concepts.

• Place variable declarations and dependent functions logically.

• Enforce team consistency using automated formatters (Linters/Prettier).

3. The Newspaper Metaphor #

• The Headline: The top of the file (the class name) should instantly tell you what the file is about.

• The Synopsis: The first few public functions should give you a high-level overview of the class's primary behavior.

• The Details: As you scroll down the file, the functions become lower-level and more detailed (the private helper functions).

4. Vertical Formatting (Spacing) #

• Separating Concepts: Every blank line is a visual cue that a new, distinct concept is starting.

• *Rule:* There should be a blank line between the package declaration, the imports, and the class declaration.

• *Rule:* There should be a blank line between every function.

• Vertical Density: Lines of code that are tightly related should appear vertically dense (no blank lines between them). If you have three lines calculating a tax total, do not put blank lines between them.

5. Horizontal Formatting (Width) #

• The Limit: You should never have to scroll horizontally to read a line of code. Historically, the limit was 80 characters. With modern wide monitors, 100 or 120 characters is acceptable.

• Indentation: This is non-negotiable. Indentation makes the hierarchy of scope (Classes -> Methods -> Loops -> Ifs) instantly visible. Code that is incorrectly indented is mathematically correct but humanly unreadable.

6. Variable and Function Placement #

• Variables: Variables should be declared as close to their usage as possible. Do not declare a variable at the top of a 50-line function if it is only used on line 48.

• Instance Variables: Class variables (properties) should be declared at the absolute top of the class.

• Dependent Functions: If Function A calls Function B, they should be vertically close to each other. Ideally, the caller (A) should be directly above the callee (B). This follows the Newspaper Metaphor.

7. Diagrams/Visual Suggestions #

[ File Top ]
class CheckoutService {
    
    // 1. Instance Variables (State)
    private $paymentGateway;

    // 2. High-Level Public API (The Synopsis)
    public function processOrder($order) {
        $this->validate($order);
        $this->charge($order);
    }

    // 3. Low-Level Private Helpers (The Details)
    private function validate($order) { ... }
    private function charge($order) { ... }
}
[ File Bottom ]

8. Best Practices #

• Automate the Arguments: Never argue about formatting in a Pull Request. Use an automated tool (like PHP_CodeSniffer, Prettier, or ESLint). The team agrees on a configuration file once. When a developer saves the file, the tool automatically formats the code. If it fails the Linter in the CI/CD pipeline, the code is rejected.

9. Common Mistakes #

• The Solo Artist: A developer joins a team and decides they prefer 2-space indentation, while the rest of the 50-person team uses 4-space indentation. They reformat every file they touch to their personal preference. This destroys the Git history and infuriates the team. Team rules trump individual preference.

10. Mini Project: Fix Formatting #

public function calcTotal($items){$total=0;foreach($items as $item){
if($item->isTaxable){$total+=$item->price*1.2;}else{$total+=$item->price;}
}return $total;}

*After (Cleaned):*

public function calculateTotal(array $items): float 
{
    $total = 0.0;

    foreach ($items as $item) {
        if ($item->isTaxable()) {
            $total += $item->price * 1.2;
        } else {
            $total += $item->price;
        }
    }

    return $total;
}

11. Practice Exercises #

1. 1. Explain the "Newspaper Metaphor" in relation to organizing the methods within a Class file.

1. 2. Why should variables be declared as close to their usage as possible, rather than at the very top of a large function?

12. MCQs with Answers #

13. Interview Questions #

• Q: Your team constantly argues during Code Reviews about whether opening braces { should be on the same line or a new line. How do you resolve this conflict permanently and stop wasting time?

• Q: Explain how indentation physically communicates the "Scope" of execution to a human reader.

• Q: A developer declares 15 variables at the top of a function, but most of them aren't used until line 50. Why is this a bad practice, and how does it relate to the concept of "Mental Memory Capacity"?

14. FAQs #

15. Summary #

16. Next Chapter Recommendation #