Cease Writing Messy Python: A Clear Code Crash Course

Picture by Creator | Ideogram

In case you’ve been coding in Python for some time, you’ve got most likely mastered the fundamentals, constructed a couple of initiatives. And now you are your code pondering: “This works, however… it is not precisely one thing I might proudly present in a code assessment.” We have all been there.

However as you retain coding, writing clear code turns into as necessary as writing practical code. On this article, I’ve compiled sensible strategies that may show you how to go from “it runs, do not contact it” to “that is truly maintainable.”

🔗 Hyperlink to the code on GitHub

1. Mannequin Knowledge Explicitly. Do not Go Round Dicts

 
Dictionaries are tremendous versatile in Python and that is exactly the issue. Whenever you go round uncooked dictionaries all through your code, you are inviting typos, key errors, and confusion about what knowledge ought to truly be current.

As an alternative of this:

def process_user(user_dict):
    if user_dict['status'] == 'lively':  # What if 'standing' is lacking?
        send_email(user_dict['email'])   # What if it is 'mail' in some locations?
        
        # Is it 'identify', 'full_name', or 'username'? Who is aware of!
        log_activity(f"Processed {user_dict['name']}")

This code will not be sturdy as a result of it assumes dictionary keys exist with out validation. It provides no safety towards typos or lacking keys, which can trigger KeyError exceptions at runtime. There’s additionally no documentation of what fields are anticipated.

Do that:

from dataclasses import dataclass
from typing import Optionally available

@dataclass
class Person:
    id: int
    e mail: str
    full_name: str
    standing: str
    last_login: Optionally available[datetime] = None

def process_user(person: Person):
    if person.standing == 'lively':
        send_email(person.e mail)
        log_activity(f"Processed {person.full_name}")

Python’s @dataclass decorator offers you a clear, express construction with minimal boilerplate. Your IDE can now present autocomplete for attributes, and you will get quick errors if required fields are lacking.

For extra complicated validation, contemplate Pydantic:

from pydantic import BaseModel, EmailStr, validator

class Person(BaseModel):
    id: int
    e mail: EmailStr  # Validates e mail format
    full_name: str
    standing: str
    
    @validator('standing')
    def status_must_be_valid(cls, v):
        if v not in {'lively', 'inactive', 'pending'}:
            increase ValueError('Have to be lively, inactive or pending')
        return v

Now your knowledge validates itself, catches errors early, and paperwork expectations clearly.

2. Use Enums for Recognized Selections

 
String literals are susceptible to typos and supply no IDE autocomplete. The validation solely occurs at runtime.

As an alternative of this:

def process_order(order, standing):
    if standing == 'pending':
        # course of logic
    elif standing == 'shipped':
        # completely different logic
    elif standing == 'delivered':
        # extra logic
    else:
        increase ValueError(f"Invalid standing: {standing}")
        
# Later in your code...
process_order(order, 'shiped')  # Typo! However no IDE warning

 
Do that:

from enum import Enum, auto

class OrderStatus(Enum):
    PENDING = 'pending'
    SHIPPED = 'shipped'
    DELIVERED = 'delivered'
    
def process_order(order, standing: OrderStatus):
    if standing == OrderStatus.PENDING:
        # course of logic
    elif standing == OrderStatus.SHIPPED:
        # completely different logic
    elif standing == OrderStatus.DELIVERED:
        # extra logic
    
# Later in your code...
process_order(order, OrderStatus.SHIPPED)  # IDE autocomplete helps!

 
Whenever you’re coping with a set set of choices, an Enum makes your code extra sturdy and self-documenting.

With enums:

• Your IDE offers autocomplete ideas
• Typos grow to be (nearly) not possible
• You possibly can iterate by all attainable values when wanted

Enum creates a set of named constants. The kind trace standing: OrderStatus paperwork the anticipated parameter kind. Utilizing OrderStatus.SHIPPED as a substitute of a string literal permits IDE autocomplete and catches typos at growth time.

3. Use Key phrase-Solely Arguments for Readability

 
Python’s versatile argument system is highly effective, however it will probably result in confusion when operate calls have a number of non-obligatory parameters.

As an alternative of this:

def create_user(identify, e mail, admin=False, notify=True, non permanent=False):
    # Implementation
    
# Later in code...
create_user("John Smith", "[email protected]", True, False)

 
Wait, what do these booleans imply once more?

When referred to as with positional arguments, it is unclear what the boolean values symbolize with out checking the operate definition. Is True for admin, notify, or one thing else?

Do that:

def create_user(identify, e mail, *, admin=False, notify=True, non permanent=False):
    # Implementation

# Now you need to use key phrases for non-obligatory args
create_user("John Smith", "[email protected]", admin=True, notify=False)

The *, syntax forces all arguments after it to be specified by key phrase. This makes your operate calls self-documenting and prevents the “thriller boolean” drawback the place readers cannot inform what True or False refers to with out studying the operate definition.

This sample is particularly helpful in API calls and the like, the place you need to guarantee readability on the name website.

4. Use Pathlib Over os.path

 
Python’s os.path module is practical however clunky. The newer pathlib module offers an object-oriented strategy that is extra intuitive and fewer error-prone.

As an alternative of this:

import os

data_dir = os.path.be part of('knowledge', 'processed')
if not os.path.exists(data_dir):
    os.makedirs(data_dir)

filepath = os.path.be part of(data_dir, 'output.csv')
with open(filepath, 'w') as f:
    f.write('resultsn')
    
# Test if we now have a JSON file with the identical identify
json_path = os.path.splitext(filepath)[0] + '.json'
if os.path.exists(json_path):
    with open(json_path) as f:
        knowledge = json.load(f)

 
This makes use of string manipulation with os.path.be part of() and os.path.splitext() for path dealing with. Path operations are scattered throughout completely different capabilities. The code is verbose and fewer intuitive.

Do that:

from pathlib import Path

data_dir = Path('knowledge') / 'processed'
data_dir.mkdir(dad and mom=True, exist_ok=True)

filepath = data_dir / 'output.csv'
filepath.write_text('resultsn')

# Test if we now have a JSON file with the identical identify
json_path = filepath.with_suffix('.json')
if json_path.exists():
    knowledge = json.masses(json_path.read_text())

 
Why pathlib is healthier:

• Path becoming a member of with / is extra intuitive
• Strategies like mkdir(), exists(), and read_text() are hooked up to the trail object
• Operations like altering extensions (with_suffix) are extra semantic

Pathlib handles the subtleties of path manipulation throughout completely different working techniques. This makes your code extra transportable and sturdy.

5. Fail Quick with Guard Clauses

 
Deeply nested if-statements are sometimes laborious to grasp and keep. Utilizing early returns — guard clauses — results in extra readable code.

As an alternative of this:

def process_payment(order, person):
    if order.is_valid:
        if person.has_payment_method:
            payment_method = person.get_payment_method()
            if payment_method.has_sufficient_funds(order.whole):
                attempt:
                    payment_method.cost(order.whole)
                    order.mark_as_paid()
                    send_receipt(person, order)
                    return True
                besides PaymentError as e:
                    log_error(e)
                    return False
            else:
                log_error("Inadequate funds")
                return False
        else:
            log_error("No cost methodology")
            return False
    else:
        log_error("Invalid order")
        return False

Deep nesting is difficult to comply with. Every conditional block requires monitoring a number of branches concurrently.

Do that:

def process_payment(order, person):
    # Guard clauses: test preconditions first
    if not order.is_valid:
        log_error("Invalid order")
        return False
        
    if not person.has_payment_method:
        log_error("No cost methodology")
        return False
    
    payment_method = person.get_payment_method()
    if not payment_method.has_sufficient_funds(order.whole):
        log_error("Inadequate funds")
        return False
    
    # Primary logic comes in spite of everything validations
    attempt:
        payment_method.cost(order.whole)
        order.mark_as_paid()
        send_receipt(person, order)
        return True
    besides PaymentError as e:
        log_error(e)
        return False

 
Guard clauses deal with error circumstances up entrance, lowering indentation ranges. Every situation is checked sequentially, making the circulate simpler to comply with. The primary logic comes on the finish, clearly separated from error dealing with.

This strategy scales a lot better as your logic grows in complexity.

6. Do not Overuse Listing Comprehensions

Listing comprehensions are considered one of Python’s most elegant options, however they grow to be unreadable when overloaded with complicated circumstances or transformations.

As an alternative of this:

# Arduous to parse at a look
active_premium_emails = [user['email'] for person in users_list 
                         if person['status'] == 'lively' and 
                         person['subscription'] == 'premium' and 
                         person['email_verified'] and
                         not person['email'] in blacklisted_domains]

This record comprehension packs an excessive amount of logic into one line. It is laborious to learn and debug. A number of circumstances are chained collectively, making it obscure the filter standards.

Do that:
Listed below are higher alternate options.

Choice 1: Operate with a descriptive identify

Extracts the complicated situation right into a named operate with a descriptive identify. The record comprehension is now a lot clearer, specializing in what it is doing (extracting emails) fairly than the way it’s filtering.

def is_valid_premium_user(person):
    return (person['status'] == 'lively' and
            person['subscription'] == 'premium' and
            person['email_verified'] and
            not person['email'] in blacklisted_domains)

active_premium_emails = [user['email'] for person in users_list if is_valid_premium_user(person)]

Choice 2: Conventional loop when logic is complicated

Makes use of a conventional loop with early continues for readability. Every situation is checked individually, making it simple to debug which situation is perhaps failing. The transformation logic can be clearly separated.

active_premium_emails = []
for person in users_list:
    # Complicated filtering logic
    if person['status'] != 'lively':
        proceed
    if person['subscription'] != 'premium':
        proceed
    if not person['email_verified']:
        proceed
    if person['email'] in blacklisted_domains:
        proceed
        
    # Complicated transformation logic
    e mail = person['email'].decrease().strip()
    active_premium_emails.append(e mail)

Listing comprehensions ought to make your code extra readable, not much less. When the logic will get complicated:

• Break complicated circumstances into named capabilities
• Think about using an everyday loop with early continues
• Cut up complicated operations into a number of steps

Bear in mind, the objective is readability.

7. Write Reusable Pure Capabilities

 
A operate is a pure operate if it produces the identical output for a similar inputs at all times. Additionally, it has no unwanted side effects.

As an alternative of this:

total_price = 0  # International state

def add_item_price(item_name, amount):
    world total_price
    # Lookup value from world stock
    value = stock.get_item_price(item_name)
    # Apply low cost 
    if settings.discount_enabled:
        value *= 0.9
    # Replace world state
    total_price += value * amount
    
# Later in code...
add_item_price('widget', 5)
add_item_price('gadget', 3)
print(f"Complete: ${total_price:.2f}")

 
This makes use of world state (total_price) which makes testing tough.

The operate has unwanted side effects (modifying world state) and is determined by exterior state (stock and settings). This makes it unpredictable and laborious to reuse.

Do that:

def calculate_item_price(merchandise, value, amount, low cost=0):
    """Calculate closing value for a amount of things with non-obligatory low cost.
    
    Args:
        merchandise: Merchandise identifier (for logging)
        value: Base unit value
        amount: Variety of objects
        low cost: Low cost as decimal 
        
    Returns:
        Ultimate value after reductions
    """
    discounted_price = value * (1 - low cost)
    return discounted_price * amount

def calculate_order_total(objects, low cost=0):
    """Calculate whole value for a set of things.
    
    Args:
        objects: Listing of (item_name, value, amount) tuples
        low cost: Order-level low cost
        
    Returns:
        Complete value in spite of everything reductions
    """
    return sum(
        calculate_item_price(merchandise, value, amount, low cost)
        for merchandise, value, amount in objects
    )

# Later in code...
order_items = [
    ('widget', inventory.get_item_price('widget'), 5),
    ('gadget', inventory.get_item_price('gadget'), 3),
]

whole = calculate_order_total(order_items, 
                             low cost=0.1 if settings.discount_enabled else 0)
print(f"Complete: ${whole:.2f}")

The next model makes use of pure capabilities that take all dependencies as parameters.

8. Write Docstrings for Public Capabilities and Courses

 
Documentation is not (and should not be) an afterthought. It is a core a part of maintainable code. Good docstrings clarify not simply what capabilities do, however why they exist and tips on how to use them appropriately.

As an alternative of this:

def celsius_to_fahrenheit(celsius):
    """Convert Celsius to Fahrenheit."""
    return celsius * 9/5 + 32

This can be a minimal docstring that solely repeats the operate identify. Gives no details about parameters, return values, or edge circumstances.
Do that:

def celsius_to_fahrenheit(celsius):
	"""
	Convert temperature from Celsius to Fahrenheit.
	The system used is: F = C × (9/5) + 32
	Args:
    	celsius: Temperature in levels Celsius (could be float or int)
	Returns:
    	Temperature transformed to levels Fahrenheit
	Instance:
    	>>> celsius_to_fahrenheit(0)
    	32.0
    	>>> celsius_to_fahrenheit(100)
    	212.0
    	>>> celsius_to_fahrenheit(-40)
    	-40.0
	"""
	return celsius * 9/5 + 32

A very good docstring:

• Paperwork parameters and return values
• Notes any exceptions that is perhaps raised
• Gives utilization examples

Your docstrings function executable documentation that stays in sync along with your code.

9. Automate Linting and Formatting

 
Do not depend on handbook inspection to catch model points and customary bugs. Automated instruments can deal with the tedious work of making certain code high quality and consistency.

You possibly can attempt organising these linting and formatting instruments:

1. Black – Code formatter
2. Ruff – Quick linter
3. mypy – Static kind checker
4. isort – Import organizer

Combine them utilizing pre-commit hooks to robotically test and format code earlier than every commit:

1. Set up pre-commit: pip set up pre-commit
2. Create a .pre-commit-config.yaml file with the instruments configured
3. Run pre-commit set up to activate

This setup ensures constant code model and catches errors early with out handbook effort.

You possibly can test 7 Instruments To Assist Write Higher Python Code to know extra on this.

10. Keep away from Catch-All besides

 
Generic exception handlers cover bugs and make debugging tough. They catch all the pieces, together with syntax errors, reminiscence errors, and keyboard interrupts.

As an alternative of this:

attempt:
    user_data = get_user_from_api(user_id)
    process_user_data(user_data)
    save_to_database(user_data)
besides:
    # What failed? We'll by no means know!
    logger.error("One thing went flawed")

This makes use of a naked exception to deal with:

• Programming errors (like syntax errors)
• System errors (like MemoryError)
• Keyboard interrupts (Ctrl+C)
• Anticipated errors (like community timeouts)

This makes debugging extraordinarily tough, as all errors are handled the identical.

Do that:

attempt:
    user_data = get_user_from_api(user_id)
    process_user_data(user_data)
    save_to_database(user_data)
besides ConnectionError as e:
    logger.error(f"API connection failed: {e}")
    # Deal with API connection points
besides ValueError as e:
    logger.error(f"Invalid person knowledge obtained: {e}")
    # Deal with validation points
besides DatabaseError as e:
    logger.error(f"Database error: {e}")
    # Deal with database points
besides Exception as e:
    # Final resort for sudden errors
    logger.important(f"Sudden error processing person {user_id}: {e}", 
                  exc_info=True)
    # Presumably re-raise or deal with generically
    increase

Catches particular exceptions that may be anticipated and dealt with appropriately. Every exception kind has its personal error message and dealing with technique.

The ultimate besides Exception catches sudden errors, logs them with full traceback (exc_info=True), and re-raises them to keep away from silently ignoring severe points.

In case you do want a catch-all handler for some motive, use besides Exception as e: fairly than a naked besides:, and at all times log the complete exception particulars with exc_info=True.

Wrapping Up

 
I hope you get to make use of not less than a few of these practices in your code. Begin implementing them in your initiatives.

You will discover your code turning into extra maintainable, extra testable, and simpler to motive about.

Subsequent time you are tempted to take a shortcut, bear in mind: code is learn many extra occasions than it is written. Blissful clear coding?
 
 

Bala Priya C is a developer and technical author from India. She likes working on the intersection of math, programming, knowledge science, and content material creation. Her areas of curiosity and experience embrace DevOps, knowledge science, and pure language processing. She enjoys studying, writing, coding, and low! At the moment, she’s engaged on studying and sharing her information with the developer group by authoring tutorials, how-to guides, opinion items, and extra. Bala additionally creates participating useful resource overviews and coding tutorials.