3 ms·

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 suppo

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?

bear8642 5y ago
>You don't write README.md, ARCHITECTURE.md, JavaDocs, etc, at all? 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 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 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
imtringued 5y ago
Self documenting code means carefully choosing names and structuring the code in a way that there is reduced ambiguity and maximum clarity instead of compensating for low quality code with additional documentation. 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.
- ethanwillis 5y ago
  Things are in fact taken away. Code as a language doesn't tell you why it exists. It only describes a process, not the purpose of that process. 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.”
- slotrans 5y ago
  > If your code is sufficiently clear there will be nothing left to say in the comments Incorrect. The code can never tell you WHY. That's what comments are for.

bear8642 5y ago

>You don't write README.md, ARCHITECTURE.md, JavaDocs, etc, at all? 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 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 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

imtringued 5y ago

Self documenting code means carefully choosing names and structuring the code in a way that there is reduced ambiguity and maximum clarity instead of compensating for low quality code with additional documentation. 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.

ethanwillis 5y ago
Things are in fact taken away. Code as a language doesn't tell you why it exists. It only describes a process, not the purpose of that process. 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.”
slotrans 5y ago
> If your code is sufficiently clear there will be nothing left to say in the comments Incorrect. The code can never tell you WHY. That's what comments are for.