24 ms·
Even if something is surprising just because it's a novel algorithm, it warrants better documentation - but commenting the code explaining how it works will mak
by nextaccountic 1y ago
Even if something is surprising just because it's a novel algorithm, it warrants better documentation - but commenting the code explaining how it works will make the code itself less surprising!
In short, it's probably possible (and it's maybe a good engineering practice) to structure the source such as no specific part is really surprising
It reminds me how LLMs finally made people to care about having good documentation - if not for other people, for the AIs to read and understand the system
- Kichererbsen 1y agoI often find myself leaving review comments on pull requests where I was surprised. I'll state as much: This surprised me - I was expecting XYZ at this point. Or I wasn't expecting X to be in charge of Y.
- _kb 1y agoWTFs/minute is a good metric for code quality. Now your pair expressing that can be an LLM. https://blog.codinghorror.com/whos-your-coding-buddy/ https://blog.codinghorror.com/whos-your-coding-buddy/
- federiconafria 1y agoI like to say that the reviewer is always right in that sense, if something is surprising, confusing, unexpected. Since I've been looking at the code for hours, I don't have a valid perspective anymore.
- deleted 1y ago[deleted]
- philipwhiuk 1y ago> It reminds me how LLMs finally made people to care about having good documentation - if not for other people, for the AIs to read and understand the system Honestly I've mostly seen the opposite - impenetrable code translated to English by AI
- criley2 1y agoEven if the impenetrable human code was translated to English by AI, it's still useful for every future AI that will touch the code. Perhaps to get that decent documentation it took a decent bit of agentic effort (or even multiple passes using different models) to truly understand it and eliminate hallucinations, so getting that high quality and accurate summary into a comment could save a lot of tokens and time in the future.