> Personally I basically always choose to annotate them except in the very specific situation of writing beginner introductory materials, when it's not a given that the reader actually knows how to read the annotations yet.
Having just gone through your tutorial (albeit not yet with a computer in hand, that's the next step), might I suggest putting those annotations in anyway? I suspect most of the people reading the tutorial will already be programmers, and one of the most useful things I've found when reading tutorials and guides is when the code examples look as much like real code as possible. When I'm reading that initial documentation, I'm not just trying to figure out what's different about this language from other languages, but I also want a sense of what it looks like to actually read and write idiomatic code in that language - what sort of formatting conventions are there, what do variable or type names typically look like, are there any common idioms, etc. Ultimately, my goal is to get up to speed and begin writing productive code as quickly as possible, so seeing type annotations everywhere is a sign to me that type annotations are good practice and something to get used to.
In general, I found the tutorial a bit too aimed towards someone learning their first programming language, which is a demographic that I suspect are unlikely to be using Roc any time soon! Even if they are a demographic you're targeting, I wonder if they'd be better served by a separate explicit "Roc as a first programming language" document that goes through the basics. Then in the main document, do some repl stuff at the beginning, but move quickly on to what regular development work might look like - starting a new project, writing functions with types, using tasks/effects, adding tests, dependencies, etc.
With all that criticism out of the way (sorry!) I do want to say that I love pretty much everything that I've seen so far, especially the focus on practical usage. It's great to see an example CLI and an example web server right on the home page - I feel like these are often left as complete afterthoughts for these sorts of languages, but they're the sort of real-world programs that dominate software in the industry.
I'm also really excited to have a play around with the effects/tasks system. It looks really powerful, but not too complicated to actually use as a base abstraction.
And I agree that having powerful type interface can be a great tool, even if you supplement it with type annotations for the sake of explicitness. Is there an explicit type hole mechanism as well, for getting the compiler to spit out the types it expects?
Thanks for the kind words, and thanks for the feedback!
> Is there an explicit type hole mechanism as well, for getting the compiler to spit out the types it expects?
Not currently, although you can write `_` for any part of a type annotation that you don't want to bother annotating (which means that part of the type will be inferred as if you hadn't written any annotation for it), and we either have or want to have "hover to see the type" in editor extensions.
Having just gone through your tutorial (albeit not yet with a computer in hand, that's the next step), might I suggest putting those annotations in anyway? I suspect most of the people reading the tutorial will already be programmers, and one of the most useful things I've found when reading tutorials and guides is when the code examples look as much like real code as possible. When I'm reading that initial documentation, I'm not just trying to figure out what's different about this language from other languages, but I also want a sense of what it looks like to actually read and write idiomatic code in that language - what sort of formatting conventions are there, what do variable or type names typically look like, are there any common idioms, etc. Ultimately, my goal is to get up to speed and begin writing productive code as quickly as possible, so seeing type annotations everywhere is a sign to me that type annotations are good practice and something to get used to.
In general, I found the tutorial a bit too aimed towards someone learning their first programming language, which is a demographic that I suspect are unlikely to be using Roc any time soon! Even if they are a demographic you're targeting, I wonder if they'd be better served by a separate explicit "Roc as a first programming language" document that goes through the basics. Then in the main document, do some repl stuff at the beginning, but move quickly on to what regular development work might look like - starting a new project, writing functions with types, using tasks/effects, adding tests, dependencies, etc.
With all that criticism out of the way (sorry!) I do want to say that I love pretty much everything that I've seen so far, especially the focus on practical usage. It's great to see an example CLI and an example web server right on the home page - I feel like these are often left as complete afterthoughts for these sorts of languages, but they're the sort of real-world programs that dominate software in the industry.
I'm also really excited to have a play around with the effects/tasks system. It looks really powerful, but not too complicated to actually use as a base abstraction.
And I agree that having powerful type interface can be a great tool, even if you supplement it with type annotations for the sake of explicitness. Is there an explicit type hole mechanism as well, for getting the compiler to spit out the types it expects?