legacy-code-doc

name

legacy-code-doc

description

Reverse-document legacy ABAP — read a Z program/class/function group end to end, map its structure, database touchpoints, callers, and side effects, and produce structured documentation (purpose, flow, interfaces, data, risks). Use whenever the user asks "what does this program do", wants documentation for undocumented custom code, is onboarding onto an unfamiliar codebase, planning an S/4HANA migration impact analysis, or preparing a rewrite/retirement decision for old Z code. Fully read-only — safe on production.

Legacy Code Documentation

Produce documentation for ABAP objects that have none. The output is for two audiences at once: a developer who must change the code next month, and a manager deciding whether it survives the next migration.

Prerequisites

• sap-adt-mcp ≥ 0.8.1 connected to the target system (adt_ping to verify).
• NetWeaver 7.4x+ — only core ADT read endpoints are needed (source read, search, where-used). adt_read_table examples additionally need NW 7.55+; skip data sampling on older systems.
• SAP user authorizations: repository display only (S_DEVELOP display).
• Read-only mode: fully supported — this skill never writes to SAP. (It may write the documentation to a local file if the user asks.)
• Large sources: adt_get_source output is capped per call (~64 KB). For big programs paginate with firstLine/lastLine, or slice with onlyMethod. Never assume one call returned the whole object — check truncated/totalLines.

Workflow

1. Scope the object

adt_search_objects if only a fuzzy name is known. Identify the object type — the strategy differs:

• Program (PROG): fetch the main source, then list its includes (adt_browse_package on its package, or INCLUDE statements from source) and fetch each include that carries logic.
• Class (CLAS): fetch definitions first (the public contract), then implementations method by method (onlyMethod) for the ones that matter.
• Function group (FUGR): document each function module separately (adt_get_source with type function + group); shared TOP include for state.

2. Read with a checklist

While reading, collect — don't paraphrase line by line:

• Entry points: events (START-OF-SELECTION, user-commands), public methods, FM interfaces, selection screen parameters.
• Database touchpoints: every table read (SELECT/JOIN) and especially every write (INSERT/UPDATE/MODIFY/DELETE, CALL FUNCTION ... IN UPDATE TASK). Writes are the risk register.
• External calls: RFCs, BAPIs, file I/O (OPEN DATASET, GUI_*), HTTP, authority-checks, COMMIT/ROLLBACK placement.
• Configuration coupling: hardcoded values, TVARV/Z-config table reads, sy-mandt/sy-sysid branching.
• Smells worth flagging: SELECT in loops, missing authority checks before writes, swallowed exceptions, dead branches (adt_grep_source across the package helps find copy-paste siblings).

3. Map the blast radius

• adt_where_used on the main object: who calls this? A "legacy" report called by 14 other programs is infrastructure, not legacy.
• adt_list_versions / adt_compare_versions: when was it last touched, how actively does it change? (Stable-for-8-years and changed-monthly need very different documentation depth.)
• Optional, NW 7.55+: one or two adt_read_table samples on its Z tables to show real data shapes (row counts, key examples) — ask before querying business data, and keep samples small.

4. Write the document

Structure (trim sections that don't apply):

# <OBJECT> — <one-line purpose>

## What it does            (3–6 sentences, business language)
## How it's triggered      (jobs, transactions, callers — from where-used)
## Inputs / outputs        (selection screen, interfaces, files, spool)
## Data                    (tables READ / tables WRITTEN — writes first, bold)
## Control flow            (numbered happy path; branches that matter)
## External dependencies   (RFCs, BAPIs, files, config tables)
## Risks & smells          (each with file:line references)
## Change history signal   (last N versions: who, when, what theme)
## Migration notes         (S/4 readiness: deprecated statements, obsolete FMs —
                            apply the abap-clean-core skill's levels if loaded)

Cite everything as INCLUDE/METHOD:line so the next developer can jump straight in. If the user wants the doc persisted, write it to a local markdown file named after the object.

5. Batch mode

For "document the whole package": adt_browse_package to enumerate, then triage — document deeply only objects with DB writes or many callers; one-line summaries for trivial ones. State the triage rule in the output so nobody mistakes a one-liner for a full review.