3 ms·

First, TypeScript type definitions are almost the same as standard JavaScript JSDoc type annotations, so (to the level they're used in Immutable.js), yes, peopl

First, TypeScript type definitions are almost the same as standard JavaScript JSDoc type annotations, so (to the level they're used in Immutable.js), yes, people should learn them. Second, TypeScript should be considered a best practice for nontrivial JavaScript development in 2016. And pretty much any app that would benefit from Immutable.js would be "nontrivial" by that definition. Third, everyone using JavaScript or TypeScript knows what a Map is, I would hope. The docs for it that read "Immutable Map is an unordered Iterable.Keyed of (key, value) pairs with O(log32 N) gets and O(log32 N) persistent sets." are perfectly legible to me, having never used Immutable.js, just because I had a few undergrad (not "a Ph.D.") computer science classes. I don't even have a computer science degree [0] at all. I actually personally despise lowest-common-denominator docs: Docs that tell me "what a Map is and how to use it" when what I want to know are things like what its get and set performance implications are, and whether you can iterate over it, and whether that iteration will be ordered, and so forth. Sure, create a user's guide, but don't pick on the reference manual for being concise. FWIW, I'm not a big fan of Immutable.js or immutable structures at all. I'm too performance-oriented to want a layer like that between me and the underlying data structures. Criticize it for being unmaintained [1], sure, but not for having docs that aren't aimed at beginners. [0] My degree is a B.S. in Cognitive Science [1] https://news.ycombinator.com/item?id=13051458 https://news.ycombinator.com/item?id=13051458

ht85 10y ago
I feel the same about lowest common denominator, and even though facebook and google documentation can be on the far end of the austere spectrum, they are still putting out incredible libs for free. For your comment about performance, immutable structure being comparable by reference can provide huge gains in read and re-use heavy environments, thanks to memoization-like techniques.
- SomeCallMeTim 10y ago
  >For your comment about performance, immutable structure being comparable by reference can provide huge gains in read and re-use heavy environments, thanks to memoization-like techniques. Fair enough. I'm often doing things to graphics, and the concept of using immutable data when the data is a bitmap with 4Mb of pixels, and you're trying to draw hundreds of sprites or shapes to it...well, let's just say that immutable doesn't make sense for that. Even when I'm just working on a game, though, the more frequent allocations required by copy-on-write structures means more fragmentation of the heap and more deallocations later. Ideally during runtime nothing gets allocated. You may even be right that the amortized speed of using immutable structures is the same as doing it with mutable data. But anything that adds a lot of allocations and therefore adds to the frequency of garbage collection will cause (or increase) jankiness in a game. You have 16.66ms to accomplish all the work for a frame. If a garbage collector comes along and steals even 10ms, if you can't do the remaining work in 6.6ms, it will skip a frame, and users will see it. And my current game needs to run in a browser, at least mostly. So here I am. :)
Waterluvian 10y ago
Documentation should absolutely be technical, exhaustive, and.. I dunno what to call it, "written for people who know what they're doing." Then have a load of general examples to cover the non-experts and initiates. There's no faster way to learn how to begin using a library than to look at some complete examples. That's the one thing that Immutable documentation misses. I wish there was a "Show example" link on almost every non-trivial method.
Tarean 10y ago
But at least they shouldn't use phrases like `persistent sets` in the documentation. I confused that with the datatype on my first reading. Technical details are necessary but that is just creating unnecessary confusion. Compare that to the haskell documentation: A map from hashable keys to values. A map cannot contain duplicate keys; each key can map to at most one value. A HashMap makes no guarantees as to the order of its elements. The implementation is based on hash array mapped tries. A HashMap is often faster than other tree-based set types, especially when key comparison is expensive, as in the case of strings. Many operations have a average-case complexity of O(log n). The implementation uses a large base (i.e. 16) so in practice these operations are constant time.

ht85 10y ago

I feel the same about lowest common denominator, and even though facebook and google documentation can be on the far end of the austere spectrum, they are still putting out incredible libs for free. For your comment about performance, immutable structure being comparable by reference can provide huge gains in read and re-use heavy environments, thanks to memoization-like techniques.

SomeCallMeTim 10y ago
>For your comment about performance, immutable structure being comparable by reference can provide huge gains in read and re-use heavy environments, thanks to memoization-like techniques. Fair enough. I'm often doing things to graphics, and the concept of using immutable data when the data is a bitmap with 4Mb of pixels, and you're trying to draw hundreds of sprites or shapes to it...well, let's just say that immutable doesn't make sense for that. Even when I'm just working on a game, though, the more frequent allocations required by copy-on-write structures means more fragmentation of the heap and more deallocations later. Ideally during runtime nothing gets allocated. You may even be right that the amortized speed of using immutable structures is the same as doing it with mutable data. But anything that adds a lot of allocations and therefore adds to the frequency of garbage collection will cause (or increase) jankiness in a game. You have 16.66ms to accomplish all the work for a frame. If a garbage collector comes along and steals even 10ms, if you can't do the remaining work in 6.6ms, it will skip a frame, and users will see it. And my current game needs to run in a browser, at least mostly. So here I am. :)

Waterluvian 10y ago

Documentation should absolutely be technical, exhaustive, and.. I dunno what to call it, "written for people who know what they're doing." Then have a load of general examples to cover the non-experts and initiates. There's no faster way to learn how to begin using a library than to look at some complete examples. That's the one thing that Immutable documentation misses. I wish there was a "Show example" link on almost every non-trivial method.

Tarean 10y ago

But at least they shouldn't use phrases like `persistent sets` in the documentation. I confused that with the datatype on my first reading. Technical details are necessary but that is just creating unnecessary confusion. Compare that to the haskell documentation: A map from hashable keys to values. A map cannot contain duplicate keys; each key can map to at most one value. A HashMap makes no guarantees as to the order of its elements. The implementation is based on hash array mapped tries. A HashMap is often faster than other tree-based set types, especially when key comparison is expensive, as in the case of strings. Many operations have a average-case complexity of O(log n). The implementation uses a large base (i.e. 16) so in practice these operations are constant time.