The Art of Writing Clean Functions: Clean Code Practices

When writing code, always remember that it's not just for computers but for other developers too. If you leave your code untouched for a few months and don't write it cleanly, figuring out what each function does and how everything fits together can be a real challenge.

Use Descriptive Function Names

When naming functions, be clear and descriptive. A function's name should convey its purpose, making it easy for others (and yourself) to understand its role within the code.

// Bad example
function calc($a, $b) {
    return $a + $b;
}


// Good example
function calculateSum($operand1, $operand2) {
    return $operand1 + $operand2;
}        

Functions Must Do Only One Thing

Keep functions focused on a single task or responsibility. This not only makes them easier to understand but also promotes modular and reusable code.

// Bad example
function processUserData($data) {
    // Process user data, send emails, and update database
}


// Good example
function validateUserData($data) {
    // Validate user input
}

function sendEmailNotification($userEmail) {
    // Send email notification
}        

Functions Must Be Small

Strive for concise functions. Small functions are easier to comprehend and maintain. If a function becomes too lengthy, consider breaking it down into smaller, more specialized functions.

// Bad example
function processOrder($order) {
    // Long and complex logic for order processing
}


// Good example
function validateOrder($order) {
    // Validate order details
}

function updateInventory($order) {
    // Update inventory based on the order
}        

Limiting Parameters

Avoid functions with an excessive number of parameters. This simplifies function calls and reduces the likelihood of errors. If a function needs a lot of parameters, especially more than two or three, it might be a sign that it needs to be simplified or reorganized

// Bad example
function calculateTotal($price, $quantity, $discount, $tax) {
    // Complex calculation with many parameters
}

// Good example
function calculateTotal($price, $quantity) {
    // Simple calculation, additional factors handled internally
}        

Clean Organization (Spacing and Returns)

Maintain clean and consistent formatting. Use proper spacing, indentation, and line breaks to enhance readability. A well-organized structure makes the code more accessible and visually appealing.

/ Bad example
function messyCode() {
//No spacing, inconsistent indentation
$result = doSomething();return$result;
}

// Good example
function cleanCode() {
    // Proper spacing and indentation
    $result = doSomething();
    return $result;
}        

Encapsulating Conditions

Encapsulate complex conditions within well-named functions. Instead of cluttering your code with intricate logical checks, delegate them to separate functions with descriptive names. This enhances clarity and promotes code reuse.

// Bad example
if ($user->isAdmin() && $user->isActive() && $user->hasPermission()) {
    // Complex logic here
}

// Good example
if (isAdminWithPermission($user)) {
    // Encapsulated condition in a function
}

function isAdminWithPermission($user) {
    return $user->isAdmin() && $user->isActive() && $user->hasPermission();
}        

Do Not Use Flag Arguments:

Avoid using boolean flags as function parameters. If a function's behavior significantly differs based on a boolean parameter, consider splitting it into two separate functions. This improves readability and reduces potential confusion.

// Bad example
function fetchData($source, $useCache = false) {
    // Use cache if $useCache is true
}

// Good example
function fetchDataFromCache($source) {
    // Fetch data from cache
}

function fetchDataWithoutCache($source) {
    // Fetch data without using cache
}        

Know Your Language's Conventions

Adhere to the conventions and best practices of the programming language you're using. Consistency in style and naming conventions across your codebase helps maintain a unified and understandable code.

Remember, writing clean functions is not just about making the code look good but also about ensuring that it remains maintainable and easily understandable by both yourself and other developers.