If you're doing it right, your comments and documentation explain what the code is for, what it accomplishes, and the non-obvious design decisions, not the implementation details.
On that basis, "self-documenting code" needs to understand itself well enough to explain its purpose and functions to others.
Advice for programmers: think about what hints and cues you're giving other maintainers*.
If you put some resource in a common directory and then create a symbolic link to it, make sure you're only doing that because you actually are using it in two or more places.
This advice is brought to you by me double-checking again what other tests are using this particular image. There aren't any. I think there were going to be, but that hasn't happened, and probably won't.
Now it's a regular file contained in the one test-suite that actually uses it, so future me will be sure that this is the only place it's actually used.
*Bear in mind that "other maintainers" includes your future self, who's forgotten all the mental context that seemed so obvious and intuitive at the time.
The idea is that you take on one module at a time, build it yourself, and learn along the way.
I've been sitting on the fence about this for a while, but this evening it occurred to me to download the manuals and see what I can learn from there.
Holy crap! This appears to be an entire introductory course for electrical engineering, in the audio domain.
They don't just describe how to assemble the kits. They walk you through all the design decisions and gotchas, explaining how each thing works and how they interact.
Can't do anything about it myself for a month or two, but I will absolutely be investing in this. From there, I ought to be able to repair and modify all sorts of stuff.
Figured it out. The airlines have moved the seats so close together, that there are now more seats on board than the overhead storage was specced for.
And that's been aggravated by people taking stuff in the cabin that they'd have previously checked, because checked luggage is now an overpriced extra.
So I've assembled my MNT Reform - wow, that thing is a brick! If I needed to take a zombie down, I'd reach for this thing without hesitation.
It comes with a prepared image of Ubuntu, which is nice. It's all set up for use with a Reform, and it's well-integrated. So far, so good.
But.
I've been using NixOS for a few years now, and I've gotten used to having the entire system fully managed. There's no losing track of anything, because it's all right there, in a git repo of config files that's shared across my machines.
Now I'm dumped back into ad-hoc package management, where it's all on-the-spot improvisation, dead-reckoning and forensic examination, and "which edition of that thing did I install?" and it leads me to a single, heartfelt question:
How do people live like this?!!
It's a mess. It's confusing. I know I did it that way myself for 20 years or so, but... this is not good for a person's state of mind.
@KatS Non-declarative systems are scary. Plus potential bricking if an install is interfered with - usually with the only rollback being full backup restore.
I am nowhere near sufficiently Zen to handle that kind of add-on stress.