Skip to content

Code Style Guide

This guide outlines the expectations for writing Python code in this curriculum. All examples and solutions should adhere to PEP 8 so that code is consistent and easy to read.

Formatting Basics

  • Indentation: Use 4 spaces per indentation level. Tabs should not be used.
  • Line length: Limit lines to 79 characters for code and 72 characters for comments or docstrings.
  • Blank lines: Surround top-level function and class definitions with two blank lines. Methods inside classes should be separated by a single blank line.
  • Imports: Import standard library modules first, followed by third‑party modules, and finally local application imports. Use absolute imports whenever possible.
  • Whitespace: Avoid extra spaces inside parentheses, brackets, or braces. Place one space on both sides of binary operators.
  • Naming conventions: Functions, variables, and methods use snake_case. Classes use CamelCase. Constants use UPPER_CASE.

Docstring Requirements

Every function or method must include a docstring that explains its purpose, parameters, return value, and examples. Follow the template below:

def calculate_discount(price: float, discount_rate: float) -> float:
    """Calculate the discounted price based on the original price and discount rate.

    This method applies a percentage discount to the given price and returns
    the final amount. It does not handle negative prices or discount rates
    greater than 100%.

    Args:
        price (float): The original price of the item.
        discount_rate (float): The discount rate as a percentage (e.g., 15.0 for 15%).

    Returns:
        float: The discounted price.

    Raises:
        ValueError: If price is negative or discount_rate is not between 0 and 100.

    Examples:
        >>> calculate_discount(100.0, 15.0)
        85.0
    """
    ...

Docstrings should use triple double quotes and be wrapped to 72 characters per line.

Documenting Class Properties

Class attributes that store significant data should have their own docstrings immediately below the definition:

from collections import defaultdict

class TranscriptAnalyzer:
    def __init__(self) -> None:
        self.speaker_text_map: dict[str, str] = defaultdict(str)
        """Maps each speaker's name to their full combined transcript text across all topics."""

        self.topic_text_map: dict[str, str] = defaultdict(str)
        """Maps each topic name to the full combined transcript text from all speakers discussing that topic."""

        self.speaker_topic_text_map: dict[tuple[str, str], str] = defaultdict(str)
        """Maps each (speaker, topic) pair to the subset of transcript text spoken by that speaker within that topic."""

These brief docstrings describe the purpose of each property so that readers understand how data is organized.

Additional Guidelines

  • Type hints: Include PEP 484 style type hints for function arguments and return values.
  • Exceptions: Be explicit about the exceptions a function may raise in the Raises section of the docstring.
  • Logging and print statements: Use logging for debug or informational output rather than print statements in production code.
  • Testing: Write unit tests for critical logic. Name test modules with the pattern test_*.py and keep them in a dedicated tests/ folder.

Following this guide ensures that all code submitted for assignments is clean, maintainable, and ready for peer review.