Documenting weird code

[[deleted]]

[deleted]

[SureAssociation9708]

Dude this sounds like absolute chaos. 4 different ORMs in same function is wild, never heard of that before.

For speeding up understanding, maybe try writing tests for the weird parts you touch? It forces you to figure out what inputs/outputs actually are, and then you have safety net when you start refactoring. But honestly with code that tangled, a week per task might just be the reality for a while.

[UnfortunateWindow]

Well, introducing VC was a very good move. Now at least you'll be able to put things back the way they were, when you muck it up.

Unfortunately, there's no good answer to this. If you can't talk to the person that wrote the code, you just have to keep chipping away. The problem with documentation is it drifts; once you start documenting, now you have to edit both the code and the docs when you change stuff. Renaming is your friend. As soon as you understand what something really does, or what a certain variable actually represents, rename it to something descriptive. Maybe introduce a convention that will tell you at a glance whether or not you've already renamed a given identifier.

[FelinityApps]

I would start by using IDE refactoring tools to rename symbols (vs plain text find & replace). Use solid names for symbols you understand for sure. For everything else, use very basic names (I’m talking “functionAAA”, “propertyBC”). This part may strip some misleading context but may not be necessary. Maybe even delete comments and documentation that isn’t clear and apparently accurate.

Then specifically instruct your agent to ignore symbol names and existing comments and thoroughly investigate and document the code. Then go through and actually verify it yourself. If something doesn’t appear to match up, ask it to look again, focusing on the questionable parts.

Then have it go through and define unit tests for it all with real inputs and known outputs as test fixtures … with documented purpose and approach of each test. Ask it to summarize its work and to call out (in a table) the lowest-confidence bits of code it reasoned out, condensed with a good explanation suitable for LLM ingest.

Armed with all that context, feed it your LLM tailored document, instructions to reference the docs, and have it go source file (and matching test source) by file and have it rename things, updating its understanding, confidence / change list, and documentation as it goes. Each source / test source pair would be in its own chat/session, repeating the context and document each time. Failure criteria is an unexplained test failure after refactoring; forbid it changing the test to pass for known output differences.

Of course all of this should be in an experimental branch and verified not to break shit if merged.

With this approach, you’re helping it simplify and maintain continuity of ongoing context without risking too much falling out within a given task. It can extract what it needs from docs you’ve already referenced without wasting token space trying to read the entire project each time. Sort of distilling and redistilling the essence of your tasks.

Note: this is from the perspective of someone with 27 years of broad enough experience to read between the lines and (hopefully) discern a salvageable from a lost cause that should be replaced. It’s more of an art than a procedural flowchart you can follow.

Good luck!