Finding your way around a codebase

Three ways to look at code you do not know: search the names, search the contents, or open the file. They are a ladder in increasing order of cost, and you enter it at the rung that matches what you already know.

Common questions

1. What is the difference between searching names and searching contents?
   A name search is a wildcard over folder locations and it never reads the contents, so it hands back a list of paths. A content search takes a pattern, opens everything you have not opened and hands back only the lines that matched.
2. How do the three compare on cost?
   A name search opens nothing, a content search opens everything and returns only the matching lines, and reading puts the whole file in front of you. That is increasing order of cost, so spend the cheap wide ones first to earn the expensive narrow one.
3. How do I know which rung to start on?
   By what you already hold. The convention gets you in at names, a string or a symbol gets you in at contents, and a known entry point gets you straight to reading.
4. Why can I trust a filename to tell me anything?
   Because filenames carry convention, so the name tells you what kind of thing a file is before you open it. A path is really three signals: the location, the extension and the name.
5. Are all three signals equally reliable?
   No. Location and extension are mostly enforced by the framework or the build, so they hold. The name is the one part a person chose freely, which is why it carries the most meaning when it is good and misleads when it is not.
6. When should I rewrite a file rather than edit it?
   The line is whether the current state is actually in front of you. If it is, a rewrite loses nothing you did not intend. If it is not, a rewrite quietly drops whatever you could not see.
7. An edit failed because the anchor was not unique. What does that mean?
   That refusal is evidence rather than an obstacle. It means the file is not shaped the way you thought, so the move is to zoom out and look at how things fit together before deciding what to do.
8. Widen the anchor or rewrite the file?
   Widening bets you understand the local shape, rewriting bets you understand the whole file. Either way you need the confidence first, which usually means a better understanding rather than a bigger hammer.
9. A search found four usages. Can I trust that number?
   Not on its own. A wrapper can re-export something under another name and every caller downstream uses that name instead, so a name search under-reports when the thing and its name come apart.
10. How do I find the real number?
    Two stages. Find all the exported names first, the real surface including whatever the wrappers renamed it to, then search for each of those. And remember the code tells you what can happen where the log tells you what did.

Back to Ways to build it with AI. The craft around it is Working with AI.