DEV Community

Dhenmark Arquiza
Dhenmark Arquiza

Posted on

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
Enter fullscreen mode Exit fullscreen mode

Top comments (1)

Collapse
 
aaronfc profile image
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).