Understanding code & docs with AI

AI is a great tutor, but you must verify its lessons against reality.

The idea

Pasting a massive, undocumented legacy file into an LLM and asking "Explain how this works" is a superpower. It builds a mental model for you instantly.

However, AI will often hallucinate the why. It will assume a variable named timeout_ms is actually used as milliseconds, even if the code accidentally treats it as seconds. If you blindly copy the AI's explanation into your official Documentation, you cement a lie into your codebase.

Legacy Code (The Reality)

function pollData(timeout_ms) {
  // Legacy bug: setTimeout uses ms, 
  // but we accidentally multiply by 1000
  let t = timeout_ms * 1000;
  
  setTimeout(() => fetch('/api'), t);
}

AI Explanation

This function polls the API.

It accepts a timeout in milliseconds and pauses for exactly that duration before making the request.

The AI read the variable name timeout_ms and confidently explained the function based on it.

How it works (The Comprehension Trap)

# AI reads intent, not execution.
# If code is written poorly or has bugs, the AI will often
# "smooth over" the bugs and explain what the code was MEANT to do.

# The Doc Generation Danger:
# If you ask AI to write JSDoc/Docstrings for your codebase,
# it will write beautiful, grammatically perfect lies.

# The Fix:
# Always verify the AI's explanation against the actual execution logic.
# Run the code. Write a test. Do not blindly commit AI documentation.