Python Anti-Patterns Checklist

Python Anti-Patterns Checklist

Understanding and avoiding anti-patterns is critical for building robust, maintainable, and efficient Python code. The "Python Anti-Patterns Checklist" skill for the Happycapy Skills platform provides a practical reference for recognizing and preventing some of the most common mistakes encountered in Python projects. This checklist is not about prescribing ideal solutions, but rather about helping teams and individuals identify poor practices that can lead to bugs, technical debt, performance issues, and maintainability headaches.

What Is This Skill?

The "Python Anti-Patterns Checklist" skill is a curated list of frequent mistakes and poor coding practices ("anti-patterns") observed in Python development. It is designed as a pre-implementation and code review aid, allowing developers to catch problematic patterns before they cause issues in production. The checklist covers a variety of categories, from infrastructure-level concerns to code structure and API usage.

This skill is not a generic Python linter or style checker. Instead, it focuses on higher-level patterns that commonly result in subtle bugs or long-term maintenance problems. Examples include duplicated error handling, inappropriate use of language features, and structural mistakes that undermine code clarity and reliability.

Why Use This Skill?

Using this checklist has several clear benefits:

• Early Detection of Issues: By reviewing the list before merging or releasing code, teams can catch mistakes that automated tools might miss.
• Improved Code Quality: Avoiding anti-patterns leads to more readable, maintainable, and predictable codebases.
• Faster Debugging: When mysterious bugs arise, referencing known anti-patterns can accelerate troubleshooting.
• Team Alignment: The checklist provides a shared reference for best practices, supporting onboarding and code review discussions.
• Educational Value: The skill serves as a teaching tool for those new to Python or unfamiliar with its common pitfalls.

Anti-patterns are not always obvious, especially to developers transitioning from other languages or those new to Python. By institutionalizing their avoidance, the team reduces the risk of repeating mistakes and accumulating technical debt.

How to Use This Skill

The checklist is intended to be used as a reference during several phases of the development lifecycle:

1. During Code Review: Before merging pull requests, reviewers can consult the checklist to look for anti-patterns in submitted code.
2. Before Finalizing Implementations: Developers can self-review their work using the checklist, catching and correcting issues early.
3. While Debugging: If a bug or performance issue appears, the checklist can provide leads by highlighting patterns known to cause subtle problems.
4. During Refactoring: When modernizing or cleaning up legacy code, the checklist can guide efforts to remove entrenched poor practices.
5. For Teaching and Standardization: Teams can use the checklist as part of onboarding materials or coding standards documentation.

Example:

Infrastructure Anti-Pattern

One of the anti-patterns highlighted in this skill is scattered timeout and retry logic. Consider the following code:

## BAD:

Timeout logic duplicated everywhere
def fetch_user(user_id):
    try:
        return requests.get(url, timeout=30)
    except Timeout:
        logger.warning("Timeout fetching user")
        return None

def fetch_orders(user_id):
    try:
        return requests.get(url, timeout=30)
    except Timeout:
        logger.warning("Timeout fetching orders")
        return None

Here, timeout and retry logic is duplicated across multiple functions. This duplication increases the risk of inconsistency and makes future changes harder.

The recommended pattern is to centralize such logic:

## GOOD:

Centralized retry logic
@retry(stop=stop_after_attempt(3), wait=wait_exponential())
def http_get(url: str) -> Response:
    return requests.get(url, timeout=30)

Using a decorator or a client wrapper abstracts the retry and timeout behavior, ensuring consistency and simplifying maintenance.

Additional Examples

Other anti-patterns covered by the skill include:

• Double registration or misconfiguration of resources
• Overuse of global variables
• Improper exception handling (catching broad exceptions)
• Misuse of mutable default arguments
• Copy-pasted code instead of reusable functions or classes
• Ignoring return values from critical functions
• Unnecessary complexity in control flow, such as deeply nested conditionals

When to Use This Skill

You should reference the Python Anti-Patterns Checklist in the following scenarios:

• Code reviews prior to merging changes
• Refactoring efforts in legacy codebases
• Onboarding new team members or establishing team coding standards
• Debugging issues that are difficult to trace
• Educational sessions for sharing Python best practices

By applying the checklist consistently, teams can systematically reduce the presence of problematic patterns and improve the overall health of their codebase.

Important Notes

• Complementary Tool: This skill is best used alongside other review tools, such as linters, type checkers, and the python-design-patterns skill, which focuses on positive architectural patterns.
• Context Matters: Some anti-patterns may be acceptable in certain contexts. The checklist is not a rigid rule set but a guide for critical thinking.
• Evolving Resource: The list of anti-patterns can grow as new issues are discovered in the field, so teams should revisit and update their practices regularly.

In summary, the "Python Anti-Patterns Checklist" skill provides a practical, actionable reference to help Python developers avoid common mistakes. By integrating this checklist into regular workflows, teams can catch issues early, improve code quality, and maintain a more reliable and maintainable codebase.