4 ms·

That documentation indeed could be improved, but I guess the intention here is that basic usage is learned from the tutorials. Though it's possible to figure fr

That documentation indeed could be improved, but I guess the intention here is that basic usage is learned from the tutorials. Though it's possible to figure from that documentation alone as well (I'm reading it for the first time too, but using Haskell often): Path construction collects types of arguments into xs, then HVectElim (heterogeneous vector eliminator, or maybe "elimination") unwraps it into an appropriate function type. xs are those types, ps is PathState, st usually stands for "state". A dumb web "Hello, world!" can be written with just putStr though, using CGI (along the lines of what I've mentioned in another comment here). Or perhaps with Network.CGI ("cgi" package), which is quite a bit more straightforward than that RouteSpec, especially if one wants to quickly understand how it works. I had a similar experience (wanting to use a language for something useful, but mostly failing to) with Rust, and maybe Python (just s/wanting/having/ in that case), but I guess the problem with that was primarily in trying to find out what's the "right"/idiomatic way to do something while there's none, or to apply practices from other languages. And maybe in not having a suitable project idea at the time. Most likely there can be more reasons of that, but they seem to go away with practice, clear goals, and/or motivation.

_hardwaregeek 7y ago
Basic is the key issue here. Sure I can type this out and get a simple program working (although if I make a transcription error, I'm not super sure I can reason through the code). But if I want to build anything beyond the basic, I can't rely on the three whole tutorials on Spock^[1]. I need to start understanding the library. But at that point reading the docs is pretty frustrating. Even with your explanations, I can't see how HVectElim or xs, ps, st are okay names. Sure, it's idiomatic. But that doesn't mean its good. What was wrong with types, pathStates and state? Sure it's less terse, but in this case that's fine. Or if they wanted to keep the same naming, at least explain it in the docs! Having built a web app in Rust, I've certainly run into pain points, but nothing at this level. A library like Rocket has so much more documentation and careful examples^[2]. But also, the interfaces in Rocket are fairly simple. You write a function that returns a type that can be converted into a response. Anything you can serialize with serde can be converted into a response. With Haskell, the interfaces are that my route defining functions return a SpockCtxM ctx conn sess st () which is actually a SpockCtxT ctx (WebStateM conn sess st) With WebStateM being WebStateT conn sess st (ResourceT IO) Yeah...I can kinda infer that these are chained monads but I have no clue what bind or return does. I assume SpockCtxM is a reader monad and WebStateM is a state monad? But that should really be described in the documentation. I see that the other libraries in the tutorial are better documented than Spock, so hopefully the Haskell ecosystem is getting better at this. But I'm still not sure I'd want to build a web app in Haskell (how's package management? Did you guys ever resolve cabal vs stack?) [1]: https://www.spock.li/tutorials/ https://www.spock.li/tutorials/ [2]: https://api.rocket.rs/v0.4/rocket/ https://api.rocket.rs/v0.4/rocket/
- defanor 7y ago
  Longer names can be seen as unnecessary and duplicating information. One has to balance between being verbose and laconic when it comes to naming in general, but judging by the lack of annotations in this case, not much care was put into it being easily readable. It may be useful to report it, once that's an issue: chances are it just seemed obvious to the author, as it also often happens to code in general, and acceptable to users. If you see an insufficiently documented and/or straightforward API, and there's no good reason to use that one in particular, I think it may also be a good idea to look for alternatives, in any language. > how's package management? I think it's fine, but there are different opinions on how it should be. I prefer a better system integration and shared libraries coming from system repositories (which is usable with Debian), Cabal works fine, Stack seems to be popular, some seem to use Nix. > Did you guys ever resolve cabal vs stack? "Resolve" as in choosing a one true way to build/install things? I don't think so, but there is this annual "state of Haskell" survey that includes build tools, which was closed just a few days ago this year (but no results available yet, afaik), though there are the results from last year [1]. "State of the Haskell ecosystem" [2] may be of interest too. There certainly are imperfections/drawbacks (and/or varying approaches/opinions/preferences), and it may not be a good choice for you for making a dynamic website (I think in many cases the overall best choice is the language one is most fluent in at the time), but my replies were mostly with the "I really want to use Haskell for something useful" sentence in mind: being exposed to worse (or at least less suitable) bits and running into a dead end can be unfortunate in that case. [1] https://taylor.fausak.me/2018/11/18/2018-state-of-haskell-survey-results/ https://taylor.fausak.me/2018/11/18/2018-state-of-haskell-su... [2] https://github.com/Gabriel439/post-rfc/blob/master/sotu.md https://github.com/Gabriel439/post-rfc/blob/master/sotu.md
  - _hardwaregeek 7y ago
    The reason I ask about package management is because when I do my annual try-to-use-Haskell-for-real event, I pick either Stack or Cabal, inevitably run into issues with one and have to switch to the other. Plus I've had situations where I tried to install packages and the manager gave me the computer equivalent of a shrug. Contrast that to Cargo which works beautifully and seamlessly out of the box. However I hold out hope that Haskell is getting better and easier to use. Legitimately, this tutorial's code looks a lot better than what I've seen before. But I'm still dissatisfied with the level of naming and documentation. I get it that the names may have been obvious to the author, but it's a little worrying to me that the author didn't think about this fact when writing the documentation. Plus Spock isn't a young framework. It's my belief that anybody writing a package should know that interface names are designed to be readable and understandable. And these names aren't subtly hard to read. HVectElim just isn't a great name. That being said, I don't want to just hate on the Haskell ecosystem. I do really find the language fascinating. I just want some better documentation, more tutorials and nicer, unified tooling.

_hardwaregeek 7y ago

Basic is the key issue here. Sure I can type this out and get a simple program working (although if I make a transcription error, I'm not super sure I can reason through the code). But if I want to build anything beyond the basic, I can't rely on the three whole tutorials on Spock^[1]. I need to start understanding the library. But at that point reading the docs is pretty frustrating. Even with your explanations, I can't see how HVectElim or xs, ps, st are okay names. Sure, it's idiomatic. But that doesn't mean its good. What was wrong with types, pathStates and state? Sure it's less terse, but in this case that's fine. Or if they wanted to keep the same naming, at least explain it in the docs! Having built a web app in Rust, I've certainly run into pain points, but nothing at this level. A library like Rocket has so much more documentation and careful examples^[2]. But also, the interfaces in Rocket are fairly simple. You write a function that returns a type that can be converted into a response. Anything you can serialize with serde can be converted into a response. With Haskell, the interfaces are that my route defining functions return a SpockCtxM ctx conn sess st () which is actually a SpockCtxT ctx (WebStateM conn sess st) With WebStateM being WebStateT conn sess st (ResourceT IO) Yeah...I can kinda infer that these are chained monads but I have no clue what bind or return does. I assume SpockCtxM is a reader monad and WebStateM is a state monad? But that should really be described in the documentation. I see that the other libraries in the tutorial are better documented than Spock, so hopefully the Haskell ecosystem is getting better at this. But I'm still not sure I'd want to build a web app in Haskell (how's package management? Did you guys ever resolve cabal vs stack?) [1]: https://www.spock.li/tutorials/ https://www.spock.li/tutorials/ [2]: https://api.rocket.rs/v0.4/rocket/ https://api.rocket.rs/v0.4/rocket/

defanor 7y ago
Longer names can be seen as unnecessary and duplicating information. One has to balance between being verbose and laconic when it comes to naming in general, but judging by the lack of annotations in this case, not much care was put into it being easily readable. It may be useful to report it, once that's an issue: chances are it just seemed obvious to the author, as it also often happens to code in general, and acceptable to users. If you see an insufficiently documented and/or straightforward API, and there's no good reason to use that one in particular, I think it may also be a good idea to look for alternatives, in any language. > how's package management? I think it's fine, but there are different opinions on how it should be. I prefer a better system integration and shared libraries coming from system repositories (which is usable with Debian), Cabal works fine, Stack seems to be popular, some seem to use Nix. > Did you guys ever resolve cabal vs stack? "Resolve" as in choosing a one true way to build/install things? I don't think so, but there is this annual "state of Haskell" survey that includes build tools, which was closed just a few days ago this year (but no results available yet, afaik), though there are the results from last year [1]. "State of the Haskell ecosystem" [2] may be of interest too. There certainly are imperfections/drawbacks (and/or varying approaches/opinions/preferences), and it may not be a good choice for you for making a dynamic website (I think in many cases the overall best choice is the language one is most fluent in at the time), but my replies were mostly with the "I really want to use Haskell for something useful" sentence in mind: being exposed to worse (or at least less suitable) bits and running into a dead end can be unfortunate in that case. [1] https://taylor.fausak.me/2018/11/18/2018-state-of-haskell-survey-results/ https://taylor.fausak.me/2018/11/18/2018-state-of-haskell-su... [2] https://github.com/Gabriel439/post-rfc/blob/master/sotu.md https://github.com/Gabriel439/post-rfc/blob/master/sotu.md
- _hardwaregeek 7y ago
  The reason I ask about package management is because when I do my annual try-to-use-Haskell-for-real event, I pick either Stack or Cabal, inevitably run into issues with one and have to switch to the other. Plus I've had situations where I tried to install packages and the manager gave me the computer equivalent of a shrug. Contrast that to Cargo which works beautifully and seamlessly out of the box. However I hold out hope that Haskell is getting better and easier to use. Legitimately, this tutorial's code looks a lot better than what I've seen before. But I'm still dissatisfied with the level of naming and documentation. I get it that the names may have been obvious to the author, but it's a little worrying to me that the author didn't think about this fact when writing the documentation. Plus Spock isn't a young framework. It's my belief that anybody writing a package should know that interface names are designed to be readable and understandable. And these names aren't subtly hard to read. HVectElim just isn't a great name. That being said, I don't want to just hate on the Haskell ecosystem. I do really find the language fascinating. I just want some better documentation, more tutorials and nicer, unified tooling.