# Developer Style & Commenting Guide

Purpose: Keep code simple, readable, and focused on one responsibility. Comments should explain "why", not "what" when code is clear.

Principles
- Keep functions small (<= 40 lines). One responsibility per function.
- Use clear, descriptive names: `approveLoan`, `calculatePenalty`.
- Prefer early returns to nested conditionals.
- Use short, direct comments above blocks or tricky logic. Use full sentences, present tense.
- Avoid redundant comments (those that restate the code).
- Keep docblocks minimal: type hints and short description only for public methods.

Comment Style
- Single-line comment: `// Explain why this step is necessary.`
- Block comment for complex logic (2-3 lines max).

Examples
- Good:
  // Check if loan is eligible for approval based on credit score
  if ($client->credit_score < 600) return false;

- Not needed:
  // Increment counter by one
  $count++;

Refactoring rules
- Don’t change public behavior or signatures without tests and review.
- Focus on clarity: rename variables, extract small helpers, add comments.
- Add or update unit tests for any behavioral change.

Files to start with
- `app/Mail/*` - small, easy to refactor for naming and comments
- `app/Notifications/*` - improve message clarity and docblocks
- `app/Models/*` - clarify methods and add docblocks

Workflow
1. Create small commits per file.
2. Run tests after each change.
3. Open PR and request review; keep changes small.

⚠️ Always preserve current behavior and API unless explicitly approved.
