Exactly. Imo “self-documented” code is mostly not a thing. I’m all for descriptive variable and function names but those are not an automatic replacement for good documentation. And yes you do need to maintain the documentation and variable names too.

LLMs love to over-engineer for edge cases that don’t even exist. I have to call that out regularly in almost every PR review.

Imo it’s not that hard to fix. If someone changes code then you force them to update the associated comment as well. Don’t allow them to merge without updating the documentation.

In regard to audience, I guess I’m lucky because only engineers will read our code and I suspect that’s true for most people. I wouldn’t concern myself with beginners tbh, unless there’s some reason you really need to. I think that’d lead to unnecessarily verbose comments that wouldn’t help anyone.

I’d much rather have both “self-documenting” (which I don’t fully buy as a concept) and well-documented code at the same time.

Self-documentation has many of the same problems people point out with comments anyway.

Oh hell no it isn’t “once”. I’ve been running Linux machines at home for various purposes for well over a decade and I’m constantly having to learn new shit. Especially because some distros will break things with updates and you’re on your own to figure it out much of the time.

Linux is easier now than it’s ever been but it’s certainly not nearly as user friendly as Windows or Mac. It’s also an intimidating topic to approach with an overwhelming amount of info that the typical the user never needs to think about otherwise (what’s a distro , what DE should I use, how do I install software on my distro, etc). the aggressively unsympathetic community doesn’t help either.

Some of that isn’t the fault of Linux but the truth remains.

Uh yeah there is. Which that my games and software run without issue on Windows whereas on Linux I have to constantly fiddle with shit to make it work. But no one’s ever honest about that.

Maybe they aren’t going anywhere. Just dumping social media. I find Lemmy a lot less toxic than reddit but it’s still basically a reddit hive mind.