Naming Conventions and Best Practices

# CHAPTER 3

Naming Conventions and Best Practices #

1. Introduction #

2. Learning Objectives #

• Understand the critical importance of intention-revealing names.

• Apply distinct grammatical rules when naming Variables, Functions, and Classes.

• Identify and eliminate ambiguous or generic names (e.g., $data, $info, Manager).

• Utilize searchable names to improve navigation in large codebases.

• Standardize terminology across a team.

3. Intention-Revealing Names #

• Bad: int d; // elapsed time in days

• Clean: int elapsedTimeInDays;

4. Naming Rules by Type #

• Variables (Nouns): Variables hold data. They should be Nouns or Noun Phrases.

• *Bad:* $calculate, $is

• *Clean:* $customerRecord, $totalPrice

• Booleans (Questions): Booleans are true/false. They should read like yes/no questions.

• *Bad:* $status, $read

• *Clean:* $isActive, $hasReadPermission

• Functions/Methods (Verbs): Functions *do* things. They must be Verbs or Verb Phrases.

• *Bad:* function payment(), function data()

• *Clean:* function processPayment(), function fetchUserData()

• Classes (Nouns): Classes represent objects or concepts.

• *Bad:* class SendEmail, class ParseData (These are actions, not objects).

• *Clean:* class EmailSender, class DataParser

5. Avoiding Disinformation and Ambiguity #

• Generic Words: Words like Data, Info, Processor, or Manager are lazy. What is a DataManager? It tells the reader absolutely nothing. Be specific. Instead of DataManager, use UserAuthenticationService.

• Wrong Types: Do not name a variable $accountList if it is not actually a List (array). If it's just a single string, the word "List" is disinformation. Call it $accountGroupings or $accounts.

6. Searchable Names #

• Single-Letter Variables: Avoid them completely (except for standard loop counters like $i). If you name a variable $e, and try to search for it, you will get 50,000 results. If you name it $exceptionError, you will find it instantly.

7. Diagrams/Visual Suggestions #

Construct | Part of Speech | Bad Example       | Clean Example
-------------------------------------------------------------------------
Variable  | Noun Phrase    | $x, $data         | $userProfile, $orderTotal
Boolean   | Question       | $valid, $admin    | $isValid, $isAdmin
Function  | Verb Phrase    | page(), calc()    | renderPage(), calculateTax()
Class     | Noun           | DoLogging         | Logger, AuthenticationService

8. Best Practices #

• Pick One Word per Concept: If you fetch data from the database, decide as a team what the verb is. Is it get(), fetch(), or retrieve()? Pick *one* and use it exclusively across the entire project. Don't have getUser(), fetchOrder(), and retrieveInvoice(). Consistency prevents confusion.

9. Common Mistakes #

• Mental Mapping (The "You Know What I Mean" Trap): A developer writes $arr = [1, 2, 3]; foreach($arr as $a) { echo $a; }. The developer thinks, "It's obvious $a means the array item." Six months later, inside a 50-line loop, someone forgets what $a stands for. Never force the reader to mentally translate your abbreviations.

10. Mini Project: Refactor Naming #

class CheckStuff {
    public function doIt($d) {
        $v = true;
        foreach($d as $i) {
            if ($i['s'] == 0) { $v = false; }
        }
        return $v;
    }
}

*After (Clean):*

class UserVerificationService {
    public function areAllUsersActive(array $users): bool {
        $allActive = true;
        foreach($users as $user) {
            if ($user['status'] == 0) { 
                $allActive = false; 
            }
        }
        return $allActive;
    }
}

11. Practice Exercises #

1. 1. Critique the variable name $flag. Why is it bad, and what are three better alternatives depending on the context?

1. 2. Explain why classes should be named using Nouns (e.g., ReportGenerator) rather than Verbs (e.g., GenerateReport).

12. MCQs with Answers #

13. Interview Questions #

• Q: During a code review, you notice a developer named a boolean variable $email. How would you coach them to improve this name, and why?

• Q: Explain the concept of "Intention-Revealing Names." Why is typing a long name (e.g., $daysSinceLastLogin) preferred over a short abbreviation (e.g., $dsl)?

• Q: "Pick one word per concept." Explain this rule. What happens to a codebase when a team mixes fetchData(), getInformation(), and retrieveRecords() randomly?

14. FAQs #

15. Summary #

16. Next Chapter Recommendation #