Comment complex logic

There is a section of pathfinding code in src/ai/navmesh.cpp that future maintainers find opaque. Add inline comments explaining the purpose of each nontrivial block: why we check node.flags & Blocked, why we compute the Manhattan heuristic that way, and why we early-exit when openSet grows beyond 10,000. Keep comments under three sentences each and explain the invariants the code relies on. Ladder L1

Before you save these inline comments, shape them so a junior engineer can act on them: call out which variables are loop invariants, list the assumptions about input graph integrity, and flag the exact lines where changing the neighbor expansion could break correctness. Prefer explanatory phrasing over restating the code. Ladder L2

I annotated the early-exit that returns failure when openSet > 10,000, but in review Sam still thought it was arbitrary. I'm afraid reviewers will remove it or change the threshold. I cannot prove the scene distributions that make this necessary without running heavy simulations. What is the likely rationale I failed to communicate and how should I rephrase the comment to convince peers to keep it? Ladder L5

Every quarter a new engineer touches our pathfinder and introduces subtle regressions because the rationale behind thresholds, flags and invariants is missing. Where am I failing when explaining complex logic, and what single documentation habit reduces these regressions most effectively? Give one concrete comment pattern and one onboarding checklist item. Ladder L6