When should I use a code explainer instead of reading the code?

When you did not write it, when you wrote it more than a year ago, or when you are being asked whether it is safe to change. It is fastest for unfamiliar code with non-obvious control flow, such as parsers, state machines, retry and backoff logic, and numerical routines. It is slowest for a fifteen-line helper whose name already says what it does.

Does it explain code in other languages?

Yes, across JavaScript, TypeScript, Python, Java, C#, C++, Go, Ruby, PHP, Rust, SQL and shell.

Can I use the output as documentation?

That is what the Markdown export is for. Review it before committing. Generated explanations can misread intent, and a confidently wrong comment is worse than no comment.

Code Explainer

Code Explainer: Read unfamiliar code in one pass.

Turn a snippet into documentation: what it does, why it is built that way, what it costs, and where it will hurt.

Input

1 line0 / 20,000js⌘↵ run

paste code, or load the sample

Explanation

Nothing explained yet

Run the instrument to get what the code does, the order it executes in, its contract and cost, and where it will surprise a caller.

Drafts stay in this browser. If the explanation names a section that is not in your code, check the code before you paste the text somewhere public.

What this instrument does

Turn a snippet into documentation: what it does, the order it executes in, its preconditions and side effects, what it costs, and where it will surprise a caller.

The output is written to be pasted into a pull request, so it skips the throat-clearing and starts with what the code does.

How it works

Execution order, not source order: The walkthrough follows the order the code actually runs, including branches. Reading a function top to bottom often describes a path the function never takes.
Contract and side effects are separated: What the function requires, what it returns, and what it changes outside its own scope are listed separately. Those three are conflated in most hand-written documentation, and only one of them is safe to ignore.
Exportable: The explanation downloads as Markdown, so it can go straight into a README, a code review comment or an onboarding doc without reformatting.

Questions

When should I use a code explainer instead of reading the code?: When you did not write it, when you wrote it more than a year ago, or when you are being asked whether it is safe to change. It is fastest for unfamiliar code with non-obvious control flow, such as parsers, state machines, retry and backoff logic, and numerical routines. It is slowest for a fifteen-line helper whose name already says what it does.
Does it explain code in other languages?: Yes, across JavaScript, TypeScript, Python, Java, C#, C++, Go, Ruby, PHP, Rust, SQL and shell.
Can I use the output as documentation?: That is what the Markdown export is for. Review it before committing. Generated explanations can misread intent, and a confidently wrong comment is worse than no comment.

Other instruments

Questions about Code Explainer

All instruments