How to Summarize Code and Technical Documentation
The challenge with code summarization is that code information density is already extremely high. A 200-line function with 15 parameters, 4 error branches, and 3 external dependencies contains more distinct facts per line than almost any prose document. Summarizing code is not about removing padding (there is none in well-written code), it is about deciding which of many important details matter for the intended audience and use case.
Step 1: Choose the Right Granularity Level
Code summarization operates at different levels, and the right level depends entirely on who consumes the summary and for what purpose.
Function/method level: Produces a 1-3 sentence description of what a single function does, its parameters, return type, and side effects. This is the building block for all other levels. Use function-level summaries for: IDE documentation tooltips, code search indexes, API reference generation, and function-level memory in coding assistants like Claude Code or Cursor.
File/class level: Describes the purpose of a file or class, its public interface, key dependencies, and how it fits within the broader module. Typically 50-150 words. Use file-level summaries for: codebase navigation, onboarding documentation, and pull request context (what does the file being changed actually do).
Module/package level: Describes a group of related files, their collective purpose, inter-file relationships, and the module's external API surface. Typically 100-300 words. Use module-level summaries for: architecture documentation, dependency analysis, and high-level codebase understanding.
Repository level: Describes the entire project, its purpose, architecture, key technologies, entry points, and how to build and run it. Typically 300-800 words. This is the level of a README or an llms.txt file. Use repo-level summaries for: project discovery, contributor onboarding, and AI agent codebase context loading.
Step 2: Use Code-Aware Prompts
Standard summarization prompts ("summarize this text") produce vague descriptions when applied to code. Code-aware prompts explicitly request the structural elements that matter.
Function-level prompt: "Describe this function in 2-3 sentences. Include: (1) What the function does (its purpose, not its implementation). (2) Parameters with their types and meaning. (3) Return type and what the return value represents. (4) Any exceptions thrown or error conditions. (5) Side effects (database writes, file I/O, external API calls, state mutations). (6) Key dependencies it calls."
File-level prompt: "Describe this file's purpose in 50-150 words. Include: (1) The main class or function group and what it provides. (2) Public API surface (list the exported functions/classes with one-line descriptions). (3) External dependencies and what they provide to this file. (4) Configuration or environment requirements. Do NOT describe internal implementation details."
Critical instruction: separate what from how. Most LLMs, when summarizing code, default to describing the implementation ("it iterates over the array, filters elements matching the predicate, maps them through the transform function"). This is the "how" and it is nearly useless as a summary because anyone can read the code to see the how. What matters is the "what" and "why": "Filters and transforms customer records based on subscription status, returning only active subscribers with their billing details attached." Always instruct the model to focus on purpose, behavior, and contracts rather than implementation steps.
Handling comments and docstrings: When the source code includes comments or docstrings, instruct the model to prioritize them as intent signals: "If the code includes comments or docstrings, treat them as the developer's intended description and verify that the code matches them. If they conflict, note the discrepancy." Existing documentation is valuable context that standard code summarization often ignores.
Step 3: Handle Documentation vs Implementation Separately
Technical documentation (API docs, architecture docs, runbooks, specs) requires different summarization strategy than source code, even though both are "technical."
API documentation summarization: The key information to preserve is endpoints (or function signatures), parameters with types and constraints, authentication requirements, rate limits, error codes, and response formats. A 50-page API reference for a payment processor like Stripe should summarize into: (1) available endpoints grouped by resource, (2) authentication method, (3) common error codes and their meaning, (4) rate limits, (5) webhook events. Strip the example request/response bodies, tutorial prose, and changelog entries unless the user specifically needs them.
Architecture document summarization: Preserve: system components and their responsibilities, communication patterns (sync/async, protocols), data flow direction, deployment topology, and critical dependencies. Drop: rationale paragraphs explaining why decisions were made (unless the summary is for decision review), future roadmap items, and historical context about how the architecture evolved.
Pull request summarization: The most common code summarization task in practice. The key information is: (1) What changed (new feature, bug fix, refactor). (2) Which files were modified and why. (3) How the change affects existing behavior. (4) What tests were added or modified. (5) Any migration or deployment steps needed. Prompt the model with the diff and file context, instructing it to focus on the intent of the change rather than listing every line modification.
Step 4: Build the Codebase Summary Hierarchy
For large codebases, individual function or file summaries are not enough. Developers need to understand how pieces connect. Build a hierarchical summary tree that mirrors the directory structure.
Bottom-up composition: Start by summarizing every function in a file. Compose function summaries into a file summary. Compose file summaries within a directory into a module summary. Compose module summaries into a repository summary. Each level adds abstraction: functions describe behavior, files describe purpose, modules describe capability, repositories describe the product.
Dependency-aware summaries: At the module level and above, include dependency information: "This module depends on the auth module for user verification and the database module for persistence. It provides the REST API layer that the frontend consumes." These relationships are invisible in individual file summaries but critical for understanding the codebase architecture.
Incremental updates: When code changes (a new commit, a merged PR), you do not need to re-summarize the entire codebase. Update only the summaries for changed files, then re-compose the module and repo summaries from the updated file summaries. This makes codebase summarization sustainable for actively developed projects where hundreds of files change weekly.
Storage for AI coding assistants: The summary hierarchy is exactly what AI coding assistants need as persistent codebase context. Tools like CLAUDE.md, .cursorrules, and MCP-based memory servers can store the repo-level and module-level summaries as persistent context, giving the coding assistant a map of the codebase without consuming the entire token budget with raw source code.
Evaluation Criteria for Code Summaries
Evaluating code summaries requires different metrics than prose summaries. Readability metrics (ROUGE, BERTScore) measure word overlap with reference text, but code summaries need to be evaluated on information completeness and accuracy.
Signature coverage: Does the summary mention all public functions/methods with their parameter types and return types? For a file with 5 public functions, a summary that mentions 3 scores 60% on signature coverage.
Dependency accuracy: Does the summary correctly identify the file's imports and external dependencies? A summary that says "uses Redis for caching" when the file actually uses Memcached fails dependency accuracy.
Purpose correctness: Does a developer reading only the summary understand what the code does well enough to decide whether this file is relevant to their task? This is a human evaluation or LLM-as-judge question: "Given this summary and this developer question, would the developer correctly include or exclude this file from their investigation?"
Staleness detection: After a code change, does the existing summary still accurately describe the code? Compare the previous summary against the changed code using an LLM judge: "Does this summary accurately describe this code? List any inaccuracies." Stale summaries that no longer match the code are worse than no summary at all because they actively mislead.
Code summarization must preserve function signatures, parameter types, dependencies, and side effects that standard prose summarization strips out. Use code-aware prompts that explicitly request structural elements, separate the "what" from the "how," and build hierarchical summaries from function to file to module to repository level. Update incrementally when code changes rather than re-summarizing the entire codebase.