Comment by crabmusket | Hacker News Reader

Comment by crabmusket | Hacker News Reader

Parent Full thread

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

[2] https://austral-lang.org/spec/spec.html#rationale

[3] https://odin-lang.org/docs/faq/

[4] https://odin-lang.org/docs/overview/#soa-data-types

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.

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/

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-typ...

> 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)

Same with the section on capability security!

To go along with that I really need a "Why should I use this" type of thing.

Similar to what you are suggesting.

Reply on news.ycombinator.com