Code Review Guidelines Python

Standard Operating Procedure: Code Review Guidelines (Python)

1. Document Control & Revision History

2. Executive Summary & Scope

This document defines the mandatory protocol for conducting Python code reviews within the enterprise. The objective is to ensure code maintainability, security compliance (OWASP Top 10), and adherence to PEP 8 standards. This SOP applies to all engineers, contractors, and automated CI/CD pipelines. Failure to adhere to these standards constitutes a breach of engineering protocol and necessitates immediate remediation.

3. Prerequisites & Tool Requirements

• Version Control: Git / GitHub Enterprise.
• Static Analysis: flake8, black, isort, mypy (Type Checking).
• Security Scanning: bandit (SAST), safety (Dependency audit).
• Environment: Access to protected branch settings and CI/CD status checks.
• Documentation: Access to the enterprise Confluence technical wiki and JIRA ticket tracking.

4. Roles & Responsibilities (RACI Matrix)

5. Step-by-Step Operational Procedure

Phase I: Pre-Submission Audit

• Ensure all local linting (flake8, black) passes with zero errors.
• Confirm type hints are implemented for all public function signatures.
• Run bandit -r . and address all high-severity vulnerabilities.
• Validate unit test coverage threshold (minimum 85%).

Phase II: Reviewer Assessment

• Verify architectural alignment with existing design patterns.
• Review cyclomatic complexity; refactor any module exceeding a score of 10.
• Ensure no hardcoded credentials or sensitive environment variables exist.
• Validate error handling: No bare except: clauses permitted.

Phase III: Approval & Merge

• Resolve all "blocking" comments within the Pull Request thread.
• Confirm at least one senior engineer approval.
• Verify CI/CD pipeline green-status across all environments.
• Squash commits into logical, atomized units before final merge.

6. Quality Assurance & Verification Criteria

7. Practical Troubleshooting Scenarios

Scenario A: Dependency Vulnerability Detected

• Trigger: safety check fails during CI/CD build.
• Corrective Action:
  1. Identify the compromised package version via pip-audit.
  2. Patch to the minimum version specified by the security advisory.
  3. If no patch exists, substitute the library or implement a virtualized wrapper to isolate the vulnerability; document in Exception Log.

Scenario B: Performance Regression/Complexity Spike

• Trigger: Reviewer identifies a function with high nested complexity (O(n²) or greater) during routine inspection.
• Corrective Action:
  1. Flag for immediate refactoring to utilize Pythonic structures (e.g., generator expressions, list comprehensions, or itertools).
  2. Require a time-complexity analysis/big-O notation validation before the PR can be unblocked.

Scenario C: Unauthorized "Workaround" Code

• Trigger: Discovery of noqa markers used to bypass linting in production-bound code.
• Corrective Action:
  1. Immediately reject PR.
  2. Initiate a mandatory "Technical Debt Remediation" task.
  3. Require the author to justify the exclusion; if unjustified, the code must be refactored to conform to PEP 8.