5 ms·

I would really like if the language reference[1] had a "rationale" or "principles" section describing the decisions at a high level. At the moment it dives stra

I would really like if the language reference[1] had a "rationale" or "principles" section describing the decisions at a high level. At the moment it dives straight into the minutiae of syntax, built-in types, etc. The language marketing insists it is "data-oriented", even in the footer of every page. But I couldn't find any more detail on this. My favourite example of this is Austral, which has a detailed rationale[2] that justifies the choices made and the tradeoffs. It really helped me decide whether I was interested in the language. Odin, cited in the blog post, has a shallow rationale on its FAQ page[3], but seems to have had more time/maturity to document specific "data-oriented" features like built-in SoA[4]. [1] https://docs.onyxlang.io/book/Overview.html https://docs.onyxlang.io/book/Overview.html [2] https://austral-lang.org/spec/spec.html#rationale https://austral-lang.org/spec/spec.html#rationale [3] https://odin-lang.org/docs/faq/ https://odin-lang.org/docs/faq/ [4] https://odin-lang.org/docs/overview/#soa-data-types https://odin-lang.org/docs/overview/#soa-data-types

brendanfh 3y ago
Thanks for the feedback! I agree my documentation is very lacking in that department. I hope in the next few days to have a page in the documentation that describes my rationale, and the tradeoffs made during development.
DoesntMatter22 3y ago
To go along with that I really need a "Why should I use this" type of thing. Similar to what you are suggesting.
ReleaseCandidat 3y ago
Roc also is a great site on how to present a "new" language. Specially the sections that explain what they mean by being "fast", "friendly" and "functional". https://www.roc-lang.org/ https://www.roc-lang.org/
dwenzek 3y ago
Thanks for these links! Austral rational documentation is indeed really interesting. My preference goes into another direction (notably toward expression-based languages), but it's refreshing to read well explained design decisions. The section about linear types is also a gem to this regard. I would even consider this as a reference source to introduce the motivations and principles behind the Rust type system and borrow checker. Only the syntax would have to be made a bit more rusty. [1] https://austral-lang.org/spec/spec.html#rationale-linear-types https://austral-lang.org/spec/spec.html#rationale-linear-typ...
- mst 3y ago
  > For many people, semicolons represent the distinction between an old and crusty language and a modern one, in which case the semicolon serves a function similar to the use of Comic Sans by the OpenBSD project. That's a delightful sentence, and in context of how the design makes opinionated choices based on its goals entirely reasonable. (I don't know if I'll agree with all of those choices after I've thought about them sufficiently to be comfortable having an opinion, but I do very much appreciate that they're explicit, deliberate, and explained)
- crabmusket 3y ago
  Same with the section on capability security!

brendanfh 3y ago

Thanks for the feedback! I agree my documentation is very lacking in that department. I hope in the next few days to have a page in the documentation that describes my rationale, and the tradeoffs made during development.

DoesntMatter22 3y ago

To go along with that I really need a "Why should I use this" type of thing. Similar to what you are suggesting.

ReleaseCandidat 3y ago

Roc also is a great site on how to present a "new" language. Specially the sections that explain what they mean by being "fast", "friendly" and "functional". https://www.roc-lang.org/ https://www.roc-lang.org/

dwenzek 3y ago

Thanks for these links! Austral rational documentation is indeed really interesting. My preference goes into another direction (notably toward expression-based languages), but it's refreshing to read well explained design decisions. The section about linear types is also a gem to this regard. I would even consider this as a reference source to introduce the motivations and principles behind the Rust type system and borrow checker. Only the syntax would have to be made a bit more rusty. [1] https://austral-lang.org/spec/spec.html#rationale-linear-types https://austral-lang.org/spec/spec.html#rationale-linear-typ...

mst 3y ago
> For many people, semicolons represent the distinction between an old and crusty language and a modern one, in which case the semicolon serves a function similar to the use of Comic Sans by the OpenBSD project. That's a delightful sentence, and in context of how the design makes opinionated choices based on its goals entirely reasonable. (I don't know if I'll agree with all of those choices after I've thought about them sufficiently to be comfortable having an opinion, but I do very much appreciate that they're explicit, deliberate, and explained)
crabmusket 3y ago
Same with the section on capability security!