Yeah, I don't even know what "self-documenting code" actually means. You don't write README.md, ARCHITECTURE.md, JavaDocs, etc, at all? A new developer is supposed to go through all the codebases and figure out for himself?
Maybe? Not sure - haven't worked on enough big projects to declare answer
>A new developer is supposed to go through all the codebases and figure out for himself?
Yes to this bit - code should have very clear structure to it with appropriate comments attached, whether that's literate style as JonesForth<https://github.com/phf/forth/blob/master/x86/jonesforth.S> shows, small section header comment or whatever.
It should be very clear what section exploring does - tiny example but cat<http://9p.io/sources/plan9/sys/src/cmd/cat.c> from plan 9 very simple segmented code - deals with file opening in main loop and cat function just reads and prints text
If your code is sufficiently clear there will be nothing left to say in the comments, the comments will have to repeat what the code is already telling you which significantly diminishes the value of comments.
>You don't write README.md
I don't think people are talking about self promoting projects or self documenting projects.
>ARCHITECTURE.md
or self documenting architecture.
>JavaDocs, etc, at all?
or self documenting libraries.
Seriously, what's so hard to understand about looking at code and then understanding it because you read it instead of having to read comments to understand the code that is in front of you? You seem to be under the wrong impression that self documenting code is a negative process where things are taken away rather than added.
And unless your programs are formally verified this process that you have codified most likely will not meet the requirements to satisfy the intended purpose.
A typical non-technical "assignment" that's given before someone is fluent is to describe in excruciating detail/list of steps how to make a peanut butter and jelly sandwich. The point of the exercise is to show students that you need to remove all ambiguity. Or at least as much as possibly. What the exercise doesn't show is.. why are we making a list of steps to tell someone how to make a sandwich.
“If you give me six lines written by the hand of the best debugging programmers, I will find something in them which will hang his operating system.”
Incorrect. The code can never tell you WHY. That's what comments are for.