Jsig - precise & concise javascript signature notation | Hacker News Reader

Jsig - precise & concise javascript signature notation

github.com

25 pointsjasondenizac13 comments

TypeScript comes to mind. It's for a different purpose (jsig is meant only for humans) but formal annotations, if successful, will be read by machine.

moreover, I don't think that type annotations will provide much benefit if there's no strict process for validating them.

An automated type checker is often the implementation of such a strict process that requires least effort.

TypeScript was actually an inspiration - and jsig draws heavily on TypeScript's inspirations (especially ES6, Go, and to some extent [particularly generics], C#).

However TypeScript was optimized for building tooling. It also requires changing the actual executable code you write and investing in a workflow around the TypeScript compiler. With jsig, you just write a comment. My experience working almost exclusively in Node.js for the past year as shown me that plain JavaScript and minimal IDE support is sufficient if you embrace a philosophy of small, self-contained, loosely-coupled modules, each with their own tests and documentation. Writing this documentation in a clear way has been a pain point for me, however. jsig grew out of some of the conventions we've been using on my team to address the ad hoc or underspecified documentation we've dealt with.

With TypeScript, it's possible to write just in JavaScript and keep your TypeScript declarations in an external file (see, for example, [TSD](https://github.com/Diullei/tsd)) - but this is impractical. Plus, TypeScript does not support generic types, which are especially convenient for things like Callback<Buffer> or Promise<Buffer>.

I guess this complaint should really be pointed at TypeScript, or even to C#, but also to Jsig...

It's really sad that different languages keep pushing `=>` for "function" type, instead of `->`, which has been the standard mathematical notations for a long time...

In this case, I am deferring to the notation adopted in the upcoming version of JavaScript, ES6 - see http://wiki.ecmascript.org/doku.php?id=harmony:arrow_functio...

I think jsig's role is more to describe JavaScript, rather than to say the language is "doing it wrong"

I'm wary of things like this. They tend to require more cognitive effort than either of the alternatives: strict typing or a purist version of duck typing. That javascript makes either of those difficult or impossible (the former for obvious reasons and the latter because of flexible implicit conversion rules and an inflexible message receiver mechanism) is a failing of javascript that can't really be bandaided over with something optional.

I just think that this is, with even the best intentions, extremely prone to bitrot.

I'm actually not really sure that it's more readable than the JSDoc way : /

I think that it's fine for very small projects, but if you want to share your docs, it's better to use an already conventioned syntax, which already solves edge cases (such as deeply nested callbacks).

For reference : http://usejsdoc.org/tags-callback.html

My issue with JSdoc is that it's based around some notion of constructor-based inheritance, rather than structure. This is find if you're writing type annotations for a compiler to optimize a single codebase, but breaks down when trying to describe APIs meant to interoperate with modules written independently. Could you give examples of "deeply nested callbacks"? The example you linked to is perfectly expressible in jsig as show in this gist: https://gist.github.com/jden/5317051

JsDoc does double duty though, because it simultaneously types the code and allows auto-generation of nicely formatted documentation.

Does jsig have a provide for putting human readable comments in the signatures?

@cromwellian jsig can just be put in regular JavaScript comments. It's not really designed to be machine parseable, although a documentation generator (or other tooling) could easily extend it to do so. jsig's scope is concerned with succinctly expressing type information to programmers, whether inline with a function definition or in a readme. In that sense, it doesn't take an opinion as to how or where it should be embedded. Think of a jsig notation as a free-standing expression.

If adding signatures to a codebase, why not use the closure syntax? Because then you also get a compiler which gives you nice warnings as well as better minification.

This is awesome. Thanks for doing this.

If you have feedback, please open an issue thread or pull request on github

Reply on news.ycombinator.com