Code Is Debt

Terse, poorly named variables, and clever code is worse than verbose, well documented, thoroughly named variables with readable dsl.

Debt is proportional to the time it takes to understand, change, and extend the codebase.

Lines of code are an imperfect mapping to tech debt. And if all things truly were equal then this metric has been minimized at the expense of readability - which almost certainty impacts debt worse.

So I think the better argument here is that, "lack of theory is debt" - so ironically, perhaps the better argument is the shorter codebase is debt in the analogy to LLMs. LLM usage minimizes theory building. But this is assuming that AI doesn't continue to progress and its ability to build theory about the project (and communicate it correctly to the engineer) remains constrained.

That gave me an idea. Is it possible to ask an AI what a variable/function does in a piece of code? I've only ever used them for generation.

Absolutely, it’s a great use of the tools. I use it to explain unfamiliar idioms or large functions on a regular basis.

But it can only amplify information already present in the code or apply "common sense" from other code bases, in other ways the things a programmer already does.

In addition LLMs recognize "meaning" mostly like prose, i.e. they take the code behaviour mostly from the names of the variables and functions less from the actual behaviour. When you name everything randomly, then a LLM is way worse to recognize what the code is doing.

This means that when the code is already confusing, wit naming doesn't match behaviour than the LLM is more likely to tell you the story from the naming not the story of actual behaviour.

I do this literally every day when I'm debugging, understanding a new system, or planning my work.

I love programming as theory building. One key thing: if the program is built for a business then the theory must revolve around the business. For example, it should include things as "easiness to hire devs for this code base”, "stability of current business model” and “how important each feature is for the business”.

No. Your understanding is only as good as what you saw for yourself, no superficial explanation will serve you. Of course, the LLM will not even give you a suitable answer anyway for anything beyond trivial code snippets.

You can, but with Claude, be sure to watch what files it reads—I’ve seen close to entirely incorrect analysis due to shallow/lazy reading.

If you think it’s phoning it in, tell them to study upstream and downstream consumers, consider edge and corner cases, and what assertions any tests are making of the code in question, and to redo their analysis.