App: Code Explainer — File Analysis

A2.0 What This Teaches

• Reading files with open() and handling FileNotFoundError
• Using sys.argv to accept command-line arguments
• Embedding source code inside a prompt with an f-string template
• Detecting the programming language from the file extension
• Producing structured explanation output via a system prompt

A2.1 Application Design

1. Read the filename from sys.argv[1]
2. Read the file contents into a string
3. Build a prompt that embeds the code in a fenced code block
4. Call the API with a system prompt that enforces a structured response format
5. Print the result to the terminal

A2.2 Reading the File

# read_file.py - isolated file reading with error handling and size check.
import sys

MAX_BYTES = 50_000   # roughly 10,000-15,000 tokens depending on content

def read_source_file(path: str) -> str:
    try:
        with open(path, "r", encoding="utf-8") as f:
            source = f.read()
    except FileNotFoundError:
        print(f"Error: file not found: {path}")
        sys.exit(1)

    if len(source) > MAX_BYTES:
        print(
            f"Warning: {path} is {len(source):,} bytes. "
            "Token cost will be high. Consider explaining a smaller section."
        )

    return source

A2.3 Building the Prompt

# detect_language.py - map file extension to language name.
from pathlib import Path

EXT_TO_LANG = {
    ".py":   "Python",
    ".js":   "JavaScript",
    ".cpp":  "C++",
    ".rs":   "Rust",
    ".cs":   "C#",
    ".java": "Java",
    ".go":   "Go",
}

def detect_language(filename: str) -> str:
    ext = Path(filename).suffix.lower()
    return EXT_TO_LANG.get(ext, "code")

def build_prompt(filename: str, code: str) -> str:
    language = detect_language(filename)
    return f"Explain this {language} code:\n\n```{language}\n{code}\n```"

A2.4 The System Prompt

# system_prompt.py - the explanation format.
SYSTEM = (
    "You are a code explainer. Structure your response as:\n"
    "(1) Purpose - one sentence.\n"
    "(2) Key Components - bulleted list.\n"
    "(3) How It Works - step-by-step.\n"
    "(4) Potential Issues - any risks or gotchas."
)

A2.5 Complete Implementation

# explain.py - explain a source file using Claude.
# Usage: python explain.py <filename>

import sys
from pathlib import Path
import anthropic

MAX_BYTES = 50_000

EXT_TO_LANG = {
    ".py": "Python", ".js": "JavaScript", ".cpp": "C++",
    ".rs": "Rust",   ".cs": "C#",         ".java": "Java", ".go": "Go",
}

SYSTEM = (
    "You are a code explainer. Structure your response as:\n"
    "(1) Purpose - one sentence.\n"
    "(2) Key Components - bulleted list.\n"
    "(3) How It Works - step-by-step.\n"
    "(4) Potential Issues - any risks or gotchas."
)

def detect_language(filename: str) -> str:
    return EXT_TO_LANG.get(Path(filename).suffix.lower(), "code")

def main():
    if len(sys.argv) < 2:
        print("Usage: python explain.py <filename>")
        sys.exit(1)

    filename = sys.argv[1]

    try:
        with open(filename, "r", encoding="utf-8") as f:
            code = f.read()
    except FileNotFoundError:
        print(f"Error: file not found: {filename}")
        sys.exit(1)

    if len(code) > MAX_BYTES:
        print(f"Warning: {filename} is {len(code):,} bytes - token cost will be high.")

    language = detect_language(filename)
    prompt = f"Explain this {language} code:\n\n```{language}\n{code}\n```"

    client = anthropic.Anthropic()
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        system=SYSTEM,
        messages=[{"role": "user", "content": prompt}],
    )

    print(response.content[0].text)

if __name__ == "__main__":
    main()

A2.6 Sample Output

$ python explain.py clamp.py

(1) Purpose - Constrains a numeric value to lie within a specified minimum and maximum range.

(2) Key Components
- clamp(value, lo, hi): the single public function
- Parameters: value (the number to constrain), lo (lower bound), hi (upper bound)
- Return: the nearest boundary value if out of range, otherwise value unchanged

(3) How It Works
1. Compare value against lo - if below, return lo immediately.
2. Compare value against hi - if above, return hi.
3. If neither condition triggers, return value as-is.

(4) Potential Issues
- No type checking: passing a string raises TypeError at the comparison.
- lo > hi is not validated; results are undefined in that case.
- No docstring or type hints, which makes the expected types ambiguous.

A2.7 Detecting Language from Extension

A2.8 Exercise

if len(sys.argv) >= 3:
    question = sys.argv[2]
    prompt += f"\n\nAfter your explanation, answer this specific question: {question}"

python explain.py myfile.py "What does the main function do?"

A2.9 Common Mistakes

Key Terms