python-best-practices

PEP 8 refactoring applies consistent formatting rules—indentation, naming conventions, line length, and spacing—to make Python code readable and maintainable. Start by identifying style violations in your source files, then systematically apply PEP 8 conventions to variable names, function definitions, imports, and whitespace.

Type hints document parameter and return types using Python's typing syntax; NumPy-style docstrings describe function purpose, parameters, returns, and examples in a structured format. Adding both improves code clarity, enables static type checking, and helps other developers understand function behavior without reading implementation details.

Type hints and docstrings are essential when collaborating on projects, maintaining legacy code, or preventing runtime errors. They're particularly valuable before refactoring, deploying to production, or onboarding new team members, as they catch type mismatches early and serve as live documentation.

Import organization follows PEP 8 conventions: standard library imports first, third-party packages second, local modules last, with each group sorted alphabetically. Robust error handling uses specific exception types and context managers instead of bare except clauses, ensuring your code fails predictably and recovers gracefully.

Yes. Type hints work alongside pytest test cases and NumPy-style docstrings without conflict. pytest validates function behavior; type hints document expected input and output types; NumPy docstrings describe parameters and returns in detail. Together they create a testable, well-documented codebase.

Code quality standards define how code should be written—PEP 8 style, type hints, docstrings, error handling patterns. Refactoring is the process of applying those standards to existing code without changing its external behavior, reducing technical debt and improving maintainability.