I've been tasked with bringing some order to a massive, legacy Java monolith that has almost zero inline comments or architectural docs. My team is considering tools to help, and Amazon Q Developer's code explanation and documentation features are on the list.
Before I dive into a potential commitment, I'm looking for real-world feedback. Specifically:
* **Scale:** Has anyone used Q on a codebase with 500k+ lines? How does it handle context limits when trying to generate a high-level overview?
* **Accuracy:** For generating module or class-level summaries, did you find the explanations were *structurally correct* (e.g., "this service handles authentication") even if they missed some nuance?
* **Workflow Integration:** Did you use it primarily in the IDE, or through the web console? Was the "ask a question" model efficient for spelunking, or did you end up needing to write very precise prompts?
* **Cost Concern:** Our codebase is in a single AWS account. For a task like this, would we be looking at a per-developer Pro tier subscription, or is there a different model for broad, one-time analysis?
My ideal outcome would be a set of generated Markdown files we could then manually refine. I'm weighing Q against a combination of local, open-source code analysis tools, but the integrated AWS context could be a plus if it works well.
Key things I'm trying to avoid:
* Paying for a tool that just gives me obvious or surface-level info I could get from a file name.
* Generating documentation that is confidently incorrect about core flows.
* Getting locked into a long-term subscription for what is essentially a one-time documentation sprint.
Any experiences or gotchas would be greatly appreciated.
I just wrapped up a similar project with a sprawling Python/Django mess, so I can share some direct experience, especially on scale and accuracy.
On your scale question, Q struggled for me when asking for a *single* high-level overview of the entire codebase. The context window just isn't big enough to ingest and reason about half a million lines at once. The trick that worked was breaking it down by logical service or directory and asking for summaries piece by piece. For accuracy, the structural summaries were surprisingly solid - it correctly identified core CRUD modules and the main API entry points. It absolutely missed subtle business logic and weird legacy workarounds, but for mapping out "what is this thing supposed to do," it gave us a fantastic starting skeleton.
I used the IDE integration exclusively, and prompt precision was key. "Explain this class" got generic fluff. "Summarize the purpose of this service, its main public methods, and what data models it interacts with" yielded much more useful docs for our Markdown goal. On cost, we needed Pro tier seats for each dev actively querying, but for a focused documentation sprint, you might get away with just a couple of subscriptions for the leads doing the heavy analysis. The web console might be an option for a read-only audit, but I haven't tried that path.