Practices for Descriptive Naming Conventions in PHP: A Guide for Writing Clean and Readable Code

Descriptive naming conventions help make your code more readable, maintainable, and self-documenting. By using names that clearly communicate the purpose of variables, functions, and classes, you help both yourself and others understand your code without needing extra comments or explanation.

Here’s how you can adopt descriptive naming conventions with practical guidelines and examples in PHP:

1. Use Nouns for Class Names

• Class names should represent the entities they manage. A descriptive class name clarifies the role of the class in your system.
• Use PascalCase for class names.
• Use names that reflect the object or responsibility of the class.

Examples:

UserAccountManager: A class responsible for managing user accounts.
InvoiceGenerator: A class that handles the generation of invoices.
ShoppingCart: A class that represents the shopping cart system.

2. Use Verbs for Function and Method Names

• Methods perform actions, so they should be named with verbs or verb phrases that describe what they do.
• Use camelCase for method and function names.
• Prefix with verbs like get, set, create, update, delete, is, has, etc., for clarity.

Examples:

createUser(): Clearly states that this function creates a user.
calculateTotalAmount(): Describes the action of calculating the total amount.
isUserLoggedIn(): A method that checks whether the user is logged in.

3. Be Specific with Variable Names

• Variables should indicate what they store or represent.
• Avoid short or ambiguous names like $x, $val, $data.
• Use camelCase for variable names.
• Think about scope and intent of the variable.

Examples:

$totalOrderAmount: Stores the total amount for an order.
$userEmailAddress: Clearly shows it holds the email address of a user.
$invoiceItems: Represents the items in an invoice, not just generic $items.

4. Avoid Overly General Names

• Avoid names like $data, $info, $result unless they are exceptionally meaningful in that context.
• Provide specific context where appropriate, such as $userData, $productInfo, or $searchResult.

5. Boolean Variables Should Ask a Question

• If a variable is boolean, its name should reflect a true/false question.
• Use is, has, should, can as prefixes to make it clear it’s a boolean.

Examples:

$isActive: Clearly suggests it's a boolean for checking if something is active.
$hasAccess: Checks whether a user has access to a resource.
$canEdit: Indicates whether the current user can edit an item.

6. Constants Should Be Descriptive and Specific

• Constants should reflect immutable values and be written in UPPERCASE_SNAKE_CASE.
• Avoid generic names like DEFAULT_VALUE, and prefer more descriptive ones.

Examples:

MAX_LOGIN_ATTEMPTS: Clearly describes the maximum allowed login attempts.
DEFAULT_CURRENCY_CODE: Describes the currency code used in transactions.
ERROR_CODE_INVALID_EMAIL: A descriptive error code that relates to email validation failure.

7. Collection Naming

• If a variable represents a collection (e.g., an array of items), make it clear by using plural nouns or adding the word list.

Examples:

$userList: A collection of users.
$products: A collection of product objects.
$orderItems: An array of items in an order.

Practical Example

class ShoppingCart {
    private $cartItems = [];
    private $totalCartValue = 0;

    public function addItemToCart($productId, $quantity) {
        $itemPrice = $this->getProductPriceById($productId);
        $this->cartItems[] = [
            'productId' => $productId,
            'quantity' => $quantity,
            'price' => $itemPrice

Comments

[Aaron Fc]

This is a good guideline!

Remember you can make your life easier if you add some code-style tool (like phpcs) and follow some standard code style like PEAR's (which I don't like but it's the default in phpcs).