4 ms·

When writing a developer guide, especially to something as fundamental as "threads in Node.js", it pays to: 1) Make as few assumptions as possible regarding wh

When writing a developer guide, especially to something as fundamental as "threads in Node.js", it pays to: 1) Make as few assumptions as possible regarding what the reader knows or has experience with 2) Make code samples as complete and "copy-and-pastable" as possible. You're assuming that all developers reading this guide will effortlessly translate that TS code to JS. Using TS creates a possible barrier to understanding, which I'm sure isn't the intent of someone publishing such a guide. Better to simply write some comments or augment the prose in the guide.

danenania 8y ago
Ok, fair enough. But for anyone who has some familiarity with type systems, the lack of type signatures (or needing to mentally parse them in some other non-standard format) also acts as a barrier to understanding. Perhaps either a side-by-side view or a tab switcher would be ideal.
- crabasa 8y ago
  Except this is a guide for Node.js (JavaScript). The one assumption the author can make is that the reader knows and is comfortable with JavsScript.
  - danenania 8y ago
    Yeah I'm not trying to disagree with you there, just pointing out that TS types are an efficient way to add important context that many (like me) will appreciate, and as a popular well-defined standard I think they are superior to some other kind of ad hoc spec that is included in comments or prose or whatever. I think it would be great if more JS code examples started including type signatures, since they are useful whether or not you program in TS. But yes, there should probably also be a JS-only example in that case and/or a way to toggle them off.
    - hackerbob 8y ago
      We've been throw this game before: CoffeeScript Until TS becomes an official standard supported by ECMAScript out of the box. Were just going along with what feels or looks good and the javascript community has proven that can change from year to year.
      - danenania 8y ago
        Well, I was huge fan of CoffeeScript, so you’ve got me there. I don’t regret a single one of the (many) times I used it though. It made me and the teams I was part of significantly more productive and allowed us to produce more concise and maintainable code than we could have with plain JS. I feel the same about TypeScript today except honestly the productivity gains are a lot more dramatic.
        Yaggo 8y ago
        As a former coffeescript fan, doesn’t the extra “clutter” in typescript syntax bother you? I like CS very much myself. While I can see the benefit of having type system (in certain projects), I just can’t get over the aesthetic/syntax issue.
        true_religion 8y ago
        For me, not really. If I want to use type annotation, I need to write the types somewhere in order to communicate it to future readers. I would much rather do it via Typescripts annotations than JSDocs. It's not clutter as it was deemed necessary by the writer (me). If I don't want to use type annotations, I simply don't add them and Typescript does not force you to do so unless you tell it to.
        danenania 8y ago
        For me, most of the key CS features that made me reach for it all ended up in ES6. And while I also prefer CS indentation to braces, I don't see that as very important.
      - 8y ago

danenania 8y ago

Ok, fair enough. But for anyone who has some familiarity with type systems, the lack of type signatures (or needing to mentally parse them in some other non-standard format) also acts as a barrier to understanding. Perhaps either a side-by-side view or a tab switcher would be ideal.

crabasa 8y ago
Except this is a guide for Node.js (JavaScript). The one assumption the author can make is that the reader knows and is comfortable with JavsScript.
- danenania 8y ago
  Yeah I'm not trying to disagree with you there, just pointing out that TS types are an efficient way to add important context that many (like me) will appreciate, and as a popular well-defined standard I think they are superior to some other kind of ad hoc spec that is included in comments or prose or whatever. I think it would be great if more JS code examples started including type signatures, since they are useful whether or not you program in TS. But yes, there should probably also be a JS-only example in that case and/or a way to toggle them off.
  - hackerbob 8y ago
    We've been throw this game before: CoffeeScript Until TS becomes an official standard supported by ECMAScript out of the box. Were just going along with what feels or looks good and the javascript community has proven that can change from year to year.
    - danenania 8y ago
      Well, I was huge fan of CoffeeScript, so you’ve got me there. I don’t regret a single one of the (many) times I used it though. It made me and the teams I was part of significantly more productive and allowed us to produce more concise and maintainable code than we could have with plain JS. I feel the same about TypeScript today except honestly the productivity gains are a lot more dramatic.
      - Yaggo 8y ago
        As a former coffeescript fan, doesn’t the extra “clutter” in typescript syntax bother you? I like CS very much myself. While I can see the benefit of having type system (in certain projects), I just can’t get over the aesthetic/syntax issue.
        true_religion 8y ago
        For me, not really. If I want to use type annotation, I need to write the types somewhere in order to communicate it to future readers. I would much rather do it via Typescripts annotations than JSDocs. It's not clutter as it was deemed necessary by the writer (me). If I don't want to use type annotations, I simply don't add them and Typescript does not force you to do so unless you tell it to.
        danenania 8y ago
        For me, most of the key CS features that made me reach for it all ended up in ES6. And while I also prefer CS indentation to braces, I don't see that as very important.
    - 8y ago