5 ms·

Another perspective which makes it clear this is The Way: it brings the promise of fully self-documenting code much closer to fruition, if not all the way!

The_Colonel 2y ago
It's a false promise I stopped believing many years ago. No type system will replace docs or even comments. No type signature will give you the why, the big picture or the context. The day I stopped believing in the possibility of "self-documenting code" was the day I started writing more readable code.
- edfletcher_t137 2y ago
  > The day I stopped believing in the possibility of "self-documenting code" was the day I started writing more readable code. "More readable" is self-documenting! Doesn't matter how you get there (though it's a bummer you've lost faith), just matters that you did. > No type system will replace docs or even comments. No type signature will give you the why, the big picture or the context. Types are just one small part of the picture: did you read even the first full message, much less the full post? Are you aware of the other non-type-related benefits Rust provides? OP helpfully gave an illustrative list I'll reproduce here for you since I'm not sure you saw it: > When a callback is called are any locks held or do you need to acquire your own? What about free callbacks, are they special? What's the intended locking order? Are there special cases where some operations might take locks in some cases but not others? > Is a NULL argument allowed and valid usage, or not? What happens to reference counts in the error case? Is a returned ref counted pointer already incremented, or is it an implied borrow from a reference owned by a passed argument? > Is the return value always a valid pointer? Can it be NULL? Or maybe it's an ERR_PTR? Maybe both? What about pointers returned via indirect arguments, are those cleared to NULL on error or left alone? Is it valid to pass a NULL * if you don't need that return pointer? Only a few of those are concerned with type safety. You really should read the whole thing.
  - The_Colonel 2y ago
    > Doesn't matter how you get there (though it's a bummer you've lost faith), just matters that you did. What bothers me is exactly this attitude that all you need is Rust: > The solution is called Rust. Encode all the rules in the code and type system once, and never have to worry about them again. My point is that you can encode all important information in a formal language. It does not solve the documentation problems, it can mitigate them. That's not nitpicking, because I've met plenty of people thinking the former and their code is usually difficult to read as a consequence.

The_Colonel 2y ago

It's a false promise I stopped believing many years ago. No type system will replace docs or even comments. No type signature will give you the why, the big picture or the context. The day I stopped believing in the possibility of "self-documenting code" was the day I started writing more readable code.

edfletcher_t137 2y ago
> The day I stopped believing in the possibility of "self-documenting code" was the day I started writing more readable code. "More readable" is self-documenting! Doesn't matter how you get there (though it's a bummer you've lost faith), just matters that you did. > No type system will replace docs or even comments. No type signature will give you the why, the big picture or the context. Types are just one small part of the picture: did you read even the first full message, much less the full post? Are you aware of the other non-type-related benefits Rust provides? OP helpfully gave an illustrative list I'll reproduce here for you since I'm not sure you saw it: > When a callback is called are any locks held or do you need to acquire your own? What about free callbacks, are they special? What's the intended locking order? Are there special cases where some operations might take locks in some cases but not others? > Is a NULL argument allowed and valid usage, or not? What happens to reference counts in the error case? Is a returned ref counted pointer already incremented, or is it an implied borrow from a reference owned by a passed argument? > Is the return value always a valid pointer? Can it be NULL? Or maybe it's an ERR_PTR? Maybe both? What about pointers returned via indirect arguments, are those cleared to NULL on error or left alone? Is it valid to pass a NULL * if you don't need that return pointer? Only a few of those are concerned with type safety. You really should read the whole thing.
- The_Colonel 2y ago
  > Doesn't matter how you get there (though it's a bummer you've lost faith), just matters that you did. What bothers me is exactly this attitude that all you need is Rust: > The solution is called Rust. Encode all the rules in the code and type system once, and never have to worry about them again. My point is that you can encode all important information in a formal language. It does not solve the documentation problems, it can mitigate them. That's not nitpicking, because I've met plenty of people thinking the former and their code is usually difficult to read as a consequence.